Transitioning to mod_perl Handlers

Transitioning to mod_perl Handlers
Geoffrey Young

Overview

Overview Apache and mod_perl 101

Overview Apache and mod_perl 101 mod_perl Handler Basics

mod_perl Handler API Basics

mod_perl Handler API Basics Using the Apache Framework

mod_perl Handler API Basics Using the Apache Framework Advanced mod_perl API Features

mod_perl Handler API Basics Using the Apache Framework Advanced mod_perl API Features Transition Strategies

Apache's Pre-fork Model

Apache parent process

Apache parent process httpd (parent)

Apache parent process forks multiple child processes httpd (parent) httpd (child) httpd (child) httpd (child) httpd (child)

Roles and Responsibilities

httpd parent processes no actual requests

httpd parent processes no actual requests all requests are served by the child processes

httpd parent processes no actual requests all requests are served by the child processes requests are handled by any available child process, not necessarily the one that handled the previous request

httpd parent processes no actual requests all requests are served by the child processes requests are handled by any available child process, not necessarily the one that handled the previous request remember, the HTTP is stateless by default

Children are Individuals
httpd (parent) httpd (child) httpd (child) httpd (child) httpd (child)

Nice, Responsible Children

each httpd child processes one incoming request at a time

each httpd child processes one incoming request at a time only when the request is over is the child free to serve the next request

each httpd child processes one incoming request at a time only when the request is over is the child free to serve the next request over time httpd child processes are terminated and replaced with fresh children

Request Phases

Request Phases Apache breaks down request processing into separate, logical parts called phases

Request Phases Apache breaks down request processing into separate, logical parts called phases client request logging URI-based init content URI translation fixups file-based init MIME setting resource control

Request Phases Apache breaks down request processing into separate, logical parts called phases each request is stepped through the phases until...

Request Phases Apache breaks down request processing into separate, logical parts called phases each request is stepped through the phases until... all processing is complete

Request Phases Apache breaks down request processing into separate, logical parts called phases each request is stepped through the phases until... all processing is complete somebody throws an "error"

Request Phases Apache breaks down request processing into separate, logical parts called phases each request is stepped through the phases until... all processing is complete somebody throws an "error" developers are given the chance to hook into each phase to add custom processing

Apache Request Cycle client request

Apache Request Cycle client request GET /perl-status HTTP/1.1
Accept: text/html, image/png, image/jpeg, image/gif, image/x-xbitmap, */* Accept-Encoding: deflate, gzip, x-gzip, identity, *;q=0 Accept-Language: en Cache-Control: no-cache Connection: Keep-Alive, TE Host: User-Agent: Mozilla/4.0 (compatible; MSIE 5.0; Windows 2000) Opera [en]

Apache Request Cycle client request URI-based init

Apache Request Cycle client request URI-based init URI translation

file-based init

file-based init resource control

file-based init MIME setting resource control

fixups file-based init MIME setting resource control

Apache Request Cycle client request URI-based init content
URI translation fixups file-based init MIME setting resource control

Apache Request Cycle content HTTP/1.1 200 OK
Keep-Alive: timeout=15, max=100 Connection: Keep-Alive Transfer-Encoding: chunked Content-Type: text/html

Apache Request Cycle client request URI-based init content

Apache Request Cycle client request logging URI-based init content

So What? most Apache users don't worry about the request cycle too much...

So What? most Apache users don't worry about the request cycle too much... ...but they do use modules that plug into it

... for instance mod_rewrite:
client request URI-based init mod_rewrite: RewriteRule /favicon.ico$ /images/favicon.ico URI translation

... for instance mod_auth: AuthUserFile .htpasswd client request
URI-based init URI translation file-based init mod_auth: AuthUserFile .htpasswd resource control

... for instance mod_cgi: SetHandler cgi-script client request
URI-based init content URI translation fixups file-based init MIME setting resource control

That's great breaking down the request into distinct phases has many benefits

That's great breaking down the request into distinct phases has many benefits gives each processing point a role that can be easily managed and programmed

That's great breaking down the request into distinct phases has many benefits gives each processing point a role that can be easily managed and programmed makes Apache more like an application framework rather than a content engine

That's great, but... breaking down the request into distinct phases has many benefits gives each processing point a role that can be easily managed and programmed makes Apache more like an application framework rather than a content engine but you have to code in C

Enter mod_perl

Enter mod_perl mod_perl offers an interface to each phase of the request cycle

Enter mod_perl mod_perl offers an interface to each phase of the request cycle opens up the Apache API to Perl code

Enter mod_perl mod_perl offers an interface to each phase of the request cycle opens up the Apache API to Perl code allows you to program targeted parts of the request cycle using Perl

Enter mod_perl mod_perl offers an interface to each phase of the request cycle opens up the Apache API to Perl code allows you to program targeted parts of the request cycle using Perl we like Perl

Apache Request Cycle client request logging URI-based init content

mod_perl Interface client request PerlCleanupHandler PerlLogHandler
PerlPostReadRequestHandler logging URI-based init PerlHandler PerlTransHandler content URI translation PerlFixupHandler PerlHeaderParserHandler fixups file-based init PerlAccessHandler PerlAuthenHandler PerlAuthzHandler PerlTypeHandler MIME setting resource control

mod_perl Interface world's ugliest slide client request
PerlCleanupHandler PerlLogHandler PerlPostReadRequestHandler world's ugliest slide logging URI-based init PerlHandler PerlTransHandler content URI translation PerlFixupHandler PerlHeaderParserHandler fixups file-based init PerlAccessHandler PerlAuthenHandler PerlAuthzHandler PerlTypeHandler MIME setting resource control

mod_perl Interface client request PerlCleanupHandler PerlLogHandler
PerlPostReadRequestHandler logging URI-based init PerlHandler PerlTransHandler content URI translation PerlFixupHandler PerlHeaderParserHandler fixups file-based init PerlAccessHandler PerlAuthenHandler PerlAuthzHandler PerlTypeHandler MIME setting resource control

How? mod_perl embeds an entire perl interpreter into Apache

Why? create a persistent perl environment

Why? create a persistent perl environment increase performance

Why? create a persistent perl environment
increase performance * (for the dynamic parts)

Why? create a persistent perl environment open up the Apache API
increase performance * (for the dynamic parts) open up the Apache API

increase performance * (for the dynamic parts) open up the Apache API increase developer options

increase performance * (for the dynamic parts) open up the Apache API increase developer options because it's cool

What is mod_perl?

What is mod_perl? to the masses, mod_perl is just faster CGI a la Apache::Registry

What is mod_perl? to the masses, mod_perl is just faster CGI a la Apache::Registry leads to comparisons to FastCGI, PerlEx, and other CGI enhancement engines

What is mod_perl? to the masses, mod_perl is just faster CGI a la Apache::Registry leads to comparisons to FastCGI, PerlEx, and other CGI enhancement engines not an accurate description of mod_perl, so comparisons aren't really valid

What is mod_perl?

What is mod_perl? mod_perl is the Perl interface to the Apache API

a C extension module, just like mod_cgi or mod_rewrite

a C extension module, just like mod_cgi or mod_rewrite creates a persistent perl environment embedded within Apache

What's the Big Deal?

What's the Big Deal? mod_perl allows you to interact with and directly alter server behavior

What's the Big Deal? mod_perl allows you to interact with and directly alter server behavior gives you the ability to "program within Apache's framework instead of around it"

What's the Big Deal? mod_perl allows you to interact with and directly alter server behavior gives you the ability to "program within Apache's framework instead of around it" let's you do it in Perl instead of C

What's the Big Deal? mod_perl allows you to interact with and directly alter server behavior gives you the ability to "program within Apache's framework instead of around it" let's you do it in Perl instead of C allows you to intercept basic Apache functions and replace them with your own (sometimes devious) Perl substitutes

Ok, so what's a handler?

Ok, so what's a handler? the term handler refers to processing that occurs during any of the Apache runtime phases

Ok, so what's a handler? the term handler refers to processing that occurs during any of the Apache runtime phases this includes the request-time phases as well as the other parts of the Apache runtime, such as restarts

Ok, so what's a handler? the term handler refers to processing that occurs during any of the Apache runtime phases this includes the request-time phases as well as the other parts of the Apache runtime, such as restarts the use of "handler" for all processing hooks is mod_perl specific

Why use handlers?

Why use handlers? gives each processing point a role that can be easily managed and programmed

Why use handlers? gives each processing point a role that can be easily managed and programmed process request at the proper phase meaningful access to the Apache API break up processing into smaller parts modularize and encapsulate processing

Why use handlers? gives each processing point a role that can be easily managed and programmed process request at the proper phase meaningful access to the Apache API break up processing into smaller parts modularize and encapsulate processing makes Apache more like an application framework rather than a content engine

Why use handlers? gives each processing point a role that can be easily managed and programmed process request at the proper phase meaningful access to the Apache API break up processing into smaller parts modularize and encapsulate processing makes Apache more like an application framework rather than a content engine CPAN

Registry is just a handler

Apache::Registry is merely an (incredibly clever and amazing) mod_perl handler

Apache::Registry is merely an (incredibly clever and amazing) mod_perl handler its performance gains are made possible due to what mod_perl really is

Apache::Registry is merely an (incredibly clever and amazing) mod_perl handler its performance gains are made possible due to what mod_perl really is let's take a peek inside...

Apache::Registry

Apache::Registry Client side http://localhost/perl-bin/bar.pl

Apache::Registry Client side Server side
Server side

Server side mod_perl intercepts content generation

Server side mod_perl intercepts content generation for Apache/Registry.pm

Server side mod_perl intercepts content generation for Apache/Registry.pm calls Apache::Registry::handler(Apache->request)

Server side mod_perl intercepts content generation for Apache/Registry.pm calls Apache::Registry::handler(Apache->request) inserts wizardry

Server side mod_perl intercepts content generation for Apache/Registry.pm calls Apache::Registry::handler(Apache->request) inserts wizardry returns response to client

Wizardry, you say?

Wizardry, you say? the wizardry is basically just putting the CGI script into it's own package

Wizardry, you say? the wizardry is basically just putting the CGI script into it's own package package Apache::ROOT::perl_2dbin::foo_2epl; sub handler { BEGIN { $^W = 1; }; ... your script here... } 1;

Wizardry, you say? the wizardry is basically just putting the CGI script into it's own package package Apache::ROOT::perl_2dbin::foo_2epl; sub handler { BEGIN { $^W = 1; }; ... your script here... } 1; because the perl interpreter is persistent the (compiled) package is already in memory when called

"The dream is always the same"

the basic process for mod_perl is the same for the other request phases as for content generation (eg, Registry)

the basic process for mod_perl is the same for the other request phases as for content generation (eg, Registry) Apache passes control to mod_perl

the basic process for mod_perl is the same for the other request phases as for content generation (eg, Registry) Apache passes control to mod_perl mod_perl passes control to your Perl handler

the basic process for mod_perl is the same for the other request phases as for content generation (eg, Registry) Apache passes control to mod_perl mod_perl passes control to your Perl handler your Perl subroutine defines the status

the basic process for mod_perl is the same for the other request phases as for content generation (eg, Registry) Apache passes control to mod_perl mod_perl passes control to your Perl handler your Perl subroutine defines the status mod_perl passes status back to Apache

the basic process for mod_perl is the same for the other request phases as for content generation (eg, Registry) Apache passes control to mod_perl mod_perl passes control to your Perl handler your Perl subroutine defines the status mod_perl passes status back to Apache Apache continues along

Anatomy of a Handler

Anatomy of a Handler a mod_perl handler is just an ordinary Perl module

Anatomy of a Handler a mod_perl handler is just an ordinary Perl module visible

Anatomy of a Handler a mod_perl handler is just an ordinary Perl module visible including mod_perl extra paths

Anatomy of a Handler a mod_perl handler is just an ordinary Perl module visible including mod_perl extra paths contains a package declaration

Anatomy of a Handler a mod_perl handler is just an ordinary Perl module visible including mod_perl extra paths contains a package declaration has at least one subroutine

Anatomy of a Handler a mod_perl handler is just an ordinary Perl module visible including mod_perl extra paths contains a package declaration has at least one subroutine typically the handler() subroutine

Let's create a handler...

Let's create a handler... Object: to protect our name-based virtual hosts from proper but bad HTTP/1.0 requests

Let's create a handler... Object: to protect our name-based virtual hosts from unacceptable HTTP/1.0 requests

HTTP/1.0 and Host

HTTP/1.0 and Host HTTP/1.0 does not require a Host header

assumes a “one host per IP" configuration

assumes a “one host per IP" configuration this limitation "breaks" name-based virtual host servers for browsers that follow HTTP/1.0 to the letter

assumes a “one host per IP" configuration this limitation "breaks" name-based virtual host servers for browsers that follow HTTP/1.0 to the letter most send the Host header, so all is well

Connected to www.apache.org. Escape character is '^]'.
$ telnet 80 Trying Connected to Escape character is '^]'. GET /foo.html HTTP/1.0 HTTP/ Found Date: Tue, 04 Jun :52:55 GMT Server: Apache/ dev (Unix) Location: Content-Length: 289 Connection: close Content-Type: text/html; charset=iso <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> <html><head> <title>302 Found</title> </head><body> <h1>Found</h1> <p>The document has moved <a href=" <hr /> <address>Apache/ dev Server at dev.apache.org Port 80</address> </body></html> Connection closed by foreign host.

$ telnet 80 Trying Connected to Escape character is '^]'. GET /foo.html HTTP/1.0 HTTP/ Found Date: Tue, 04 Jun :52:55 GMT Server: Apache/ dev (Unix) Location: Content-Length: 289 Connection: close Content-Type: text/html; charset=iso <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> <html><head> <title>302 Found</title> </head><body> <h1>Found</h1> <p>The document has moved <a href=" /> <address>Apache/ dev Server at dev.apache.org Port 80</address> </body></html> Connection closed by foreign host.

$ telnet 80 Trying Connected to Escape character is '^]'. GET /foo.html HTTP/1.0 HTTP/ Found Date: Tue, 04 Jun :52:55 GMT Server: Apache/ dev (Unix) Location: Content-Length: 289 Connection: close Content-Type: text/html; charset=iso <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> <html><head> <title>302 Found</title> </head><body> <h1>Found</h1> <p>The document has moved <a href=" <hr /> <address>Apache/ dev Server at dev.apache.org Port 80</address> </body></html> Connection closed by foreign host.

$ telnet 80 Trying Connected to Escape character is '^]'. GET /foo.html HTTP/1.0 Host: HTTP/ Not Found Date: Tue, 04 Jun :56:40 GMT Server: Apache/ dev (Unix) Content-Length: 283 Content-Type: text/html; charset=iso <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> <html><head> <title>404 Not Found</title> </head><body> <h1>Not Found</h1> <p>The requested URL /foo.html was not found on this server.</p> <hr /> <address>Apache/ dev Server at Port 80</address> </body></html>

Let's create a handler... Object: to protect our name-based virtual hosts from unacceptable HTTP/1.0 requests

Let's create a handler... Object: to protect our name-based virtual hosts from unacceptable HTTP/1.0 requests Method: intercept the request prior to content-generation and return an error unless...

Let's create a handler... Object: to protect our name-based virtual hosts from unacceptable HTTP/1.0 requests Method: intercept the request prior to content-generation and return an error unless... there is a Host header

Let's create a handler... Object: to protect our name-based virtual hosts from unacceptable HTTP/1.0 requests Method: intercept the request prior to content-generation and return an error unless... there is a Host header the request is an absolute URI

package Cookbook::TrapNoHost;
use Apache::Constants qw(DECLINED BAD_REQUEST); use Apache::URI; use strict; sub handler { my $r = shift; # Valid requests for name based virtual hosting are: # requests with a Host header, or # requests that are absolute URIs. unless ($r->headers_in->get('Host') || $r->parsed_uri->hostname) { $r->custom_response(BAD_REQUEST, "Oops! Did you mean to omit a Host header?\n"); return BAD_REQUEST; } return DECLINED; 1;

use Apache::Constants qw(DECLINED BAD_REQUEST); use Apache::URI; use strict; sub handler { my $r = Apache->request; # Valid requests for name based virtual hosting are: # requests with a Host header, or # requests that are absolute URIs. unless ($r->headers_in->get('Host') || $r->parsed_uri->hostname) { $r->custom_response(BAD_REQUEST, "Oops! Did you mean to omit a Host header?\n"); return BAD_REQUEST; } return DECLINED; 1;

Setup add TrapNoHost.pm

Setup add TrapNoHost.pm to @INC
ServerRoot/lib/perl/Cookbook/TrapNoHost.pm

Setup add TrapNoHost.pm to @INC add to httpd.conf
ServerRoot/lib/perl/Cookbook/TrapNoHost.pm add to httpd.conf

Setup add TrapNoHost.pm to @INC add to httpd.conf
ServerRoot/lib/perl/Cookbook/TrapNoHost.pm add to httpd.conf PerlModule Cookbook::TrapNoHost PerlTransHandler Cookbook::TrapNoHost

Setup add TrapNoHost.pm to @INC add to httpd.conf that's it!
ServerRoot/lib/perl/Cookbook/TrapNoHost.pm add to httpd.conf PerlModule Cookbook::TrapNoHost PerlTransHandler Cookbook::TrapNoHost that's it!

Apache Request Cycle client request client request logging
URI-based init content URI translation fixups file-based init MIME setting resource control

Intercept the Request client request URI-based init URI translation

Intercept the Request client request URI-based init URI translation
HTTP/ Bad Request Date: Tue, 04 Jun :17:52 GMT Server: Apache/ dev (Unix) mod_perl/1.27_01-dev Perl/v5.8.0 Connection: close Content-Type: text/html; charset=iso Oops! Did you mean to omit a Host header?

Intercept the Request client request logging URI-based init
URI translation

Key Concepts

Key Concepts the Apache request object, $r

Key Concepts the Apache request object, $r the Apache::Table class

the Apache::URI class

the Apache::URI class return values and the Apache::Constants class

the Apache::URI class return values and the Apache::Constants class error responses and $r‑>custom_response()

Apache Request Object

Apache Request Object passed to handlers or available via Apache->request()

Apache Request Object passed to handlers or available via Apache->request() $r = shift; # passed to handler()

Apache Request Object passed to handlers or available via Apache->request() $r = shift; # passed to handler() $r = Apache->request();

Apache Request Object passed to handlers or available via Apache->request() $r = shift; # passed to handler() $r = Apache->request(); provides access to the Apache class, which provides access to request attributes

Apache Request Object passed to handlers or available via Apache->request() $r = shift; # passed to handler() $r = Apache->request(); provides access to the Apache class, which provides access to request attributes singleton-like constructor, always returning the same object

Apache::Table

Apache::Table the Apache::Table class provides the underlying API for the following request attributes...

Apache::Table the Apache::Table class provides the underlying API for the following request attributes... $r->headers_in() $r->headers_out() $r->err_headers_out() $r->dir_config() $r->subprocess_env() $r->notes() Apache::Request::param() Apache::Request::parms() in old releases

Apache::Table to manipulate Apache::Table objects, you use the provided methods

Apache::Table to manipulate Apache::Table objects, you use the provided methods get() set() add() unset() do() merge() new() clear()

Apache Table Properties

Apache tables have some nice properties

Apache tables have some nice properties case insensitive

Apache tables have some nice properties case insensitive allow for multi-valued keys

Apache tables have some nice properties case insensitive allow for multi-valued keys they also have one important limitation

Apache tables have some nice properties case insensitive allow for multi-valued keys they also have one important limitation can contain only simple strings

Apache tables have some nice properties case insensitive allow for multi-valued keys they also have one important limitation can contain only simple strings use pnotes() for Perl scalars

keeps the Net flowin'...

keeps the Net flowin'... both case-insensitivity and multiple values are key to manipulating headers

keeps the Net flowin'... both case-insensitivity and multiple values are key to manipulating headers $r->headers_out->set('Set-Cookie' => 'name=foo');

keeps the Net flowin'... both case-insensitivity and multiple values are key to manipulating headers $r->headers_out->set('Set-Cookie' => 'name=foo'); $r->headers_out->add('set-cookie' => 'name=bar');

keeps the Net flowin'... both case-insensitivity and multiple values are key to manipulating headers $r->headers_out->set('Set-Cookie' => 'name=foo'); $r->headers_out->add('set-cookie' => 'name=bar'); = $r->headers_out->get('Set-cookie');

Table Iteration

Table Iteration Apache::Table objects use a special idiom when you need to operate on every item in a table

Table Iteration Apache::Table objects use a special idiom when you need to operate on every item in a table my $input = $apr->param; # Apache::Table object $input->do(sub { my ($key, $value) $log->info("input: name = $key, value = $value"); 1; });

More Apache::Table Fun

Tired

Tired PerlSetVar MyVar "um, ok"

Tired PerlSetVar MyVar "um, ok" my $ok = $r->dir_config('MyVar');

Tired PerlSetVar MyVar "um, ok" my $ok = $r->dir_config('MyVar'); Wired

Tired PerlSetVar MyVar "um, ok" my $ok = $r->dir_config('MyVar'); Wired PerlAddVar MyVar "cool"

Tired PerlSetVar MyVar "um, ok" my $ok = $r->dir_config('MyVar'); Wired PerlAddVar MyVar "cool" = $r->dir_config->get('MyVar');

Trickery

Trickery really understanding the Apache::Table class will make you a better mod_perl programmer

Trickery really understanding the Apache::Table class will make you a better mod_perl programmer every table can be set

Trickery really understanding the Apache::Table class will make you a better mod_perl programmer every table can be set $r->headers_in() $r->headers_out() $r->err_headers_out() $r->dir_config() $r->subprocess_env() $r->notes() Apache::Request::param()

Trickery handle "what if?" cases

Trickery handle "what if?" cases
$r->headers_in->set('Set-Cookie' => 'name=foo'); my $sub = $r->lookup_uri('/scripts/foo.html');

Trickery handle "what if?" cases gratuitous exploitation
$r->headers_in->set('Set-Cookie' => 'name=foo'); my $sub = $r->lookup_uri('/scripts/foo.html'); gratuitous exploitation

Trickery handle "what if?" cases gratuitous exploitation
$r->headers_in->set('Set-Cookie' => 'name=foo'); my $sub = $r->lookup_uri('/scripts/foo.html'); gratuitous exploitation # configure "PerlSetVar Filter On" on-the-fly $r->dir_config->set(Filter => 'On');

All About URIs

All About URIs when Apache parses the incoming request, it puts parts of the URI into the request record

All About URIs when Apache parses the incoming request, it puts parts of the URI into the request record for just digging out the request URI you typically want the request attribute $r->uri()

All About URIs when Apache parses the incoming request, it puts parts of the URI into the request record for just digging out the request URI you typically want the request attribute $r->uri() my $uri = $r->uri; # $uri is "/index.html"

All About URIs when Apache parses the incoming request, it puts parts of the URI into the request record for just digging out the request URI you typically want the request attribute $r->uri() my $uri = $r->uri; # $uri is "/index.html" sometimes you need all the URI parts, like the scheme or port

Apache::URI

Apache::URI mod_perl provides the Apache::URI utility class for handling URIs

Apache::URI mod_perl provides the Apache::URI utility class for handling URIs allows for manipulating the current URI as well as constructing a new URI

Apache::URI mod_perl provides the Apache::URI utility class for handling URIs allows for manipulating the current URI as well as constructing a new URI unfortunately, it has two distinct interfaces that contain very subtle differences

Apache::URI mod_perl provides the Apache::URI utility class for handling URIs allows for manipulating the current URI as well as constructing a new URI unfortunately, it has two distinct interfaces that contain very subtle differences our code uses those differences to our advantage

Manipulating URIs

Manipulating URIs Apache::URI offers the parse() method as a constructor

Manipulating URIs Apache::URI offers the parse() method as a constructor my $uri = Apache::URI->parse($r);

Manipulating URIs Apache::URI offers the parse() method as a constructor my $uri = Apache::URI->parse($r); you can also grab an Apache::URI object from the request itself my $uri = $r->parsed_uri;

Manipulating URIs Apache::URI offers the parse() method as a constructor my $uri = Apache::URI->parse($r); you can also grab an Apache::URI object from the request itself my $uri = $r->parsed_uri; to get the URI string back, call the unparse() method

Manipulating URIs Apache::URI offers the parse() method as a constructor my $uri = Apache::URI->parse($r); you can also grab an Apache::URI object from the request itself my $uri = $r->parsed_uri; to get the URI string back, call the unparse() method $uri->path('/new/location'); $r->headers_out->set(Location => $uri->unparse);

Apache::URI methods

Apache::URI methods once you have an Apache::URI object, you can peek at or modify any part of the URI using its accessor methods

Apache::URI methods once you have an Apache::URI object, you can peek at or modify any part of the URI using its accessor methods - password() - port() - scheme() - path() - query() - more...

Apache::URI methods once you have an Apache::URI object, you can peek at or modify any part of the URI using its accessor methods - password() - port() - scheme() - path() - query() - more... unfortunately, although the objects have the same methods, they don't always behave the same...

parsed_uri()

parsed_uri() parsed_uri() returns an object populated based on $r->uri() and other parts of the request record

parsed_uri() parsed_uri() returns an object populated based on $r->uri() and other parts of the request record since the URI has undergone translation, the path_info() method will return useful information

parsed_uri() parsed_uri() returns an object populated based on $r->uri() and other parts of the request record since the URI has undergone translation, the path_info() method will return useful information Given: <Location /foo>

parsed_uri() parsed_uri() returns an object populated based on $r->uri() and other parts of the request record since the URI has undergone translation, the path_info() method will return useful information Given: <Location /foo> my $path = $r->parsed_uri->path; # "/foo" my $info = $r->parsed_uri->path_info; # "/bar"

Apache::URI->parse($r)

Apache::URI->parse($r) only looks at the incoming URI and makes no assumptions about the underlying filesystem

Apache::URI->parse($r) only looks at the incoming URI and makes no assumptions about the underlying filesystem Given: <Location /foo>

Apache::URI->parse($r) only looks at the incoming URI and makes no assumptions about the underlying filesystem Given: <Location /foo> my $path = Apache::URI->parse($r)->path; # "/foo/bar" my $info = Apache::URI->parse($r)->path_info; # undef

parsed_uri()

parsed_uri() unless the request is an absolute URI the scheme, host, and port fields will be absent

parsed_uri() unless the request is an absolute URI the scheme, host, and port fields will be absent proxy requests are absolute URIs

parsed_uri() unless the request is an absolute URI the scheme, host, and port fields will be absent proxy requests are absolute URIs Given:

Apache::URI->parse($r) uses other bits of information to construct a self-referential URI

Apache::URI->parse($r) uses other bits of information to construct a self-referential URI Given:

Apache::URI->parse($r) uses other bits of information to construct a self-referential URI Given: my $scheme = Apache::URI->parse($r)->scheme; # "http" my $host = Apache::URI->parse($r)->hostname; "

it all boils down to...

it all boils down to... the differences between Apache::URI->parse($r) and $r->parsed_uri() are very confusing

it all boils down to... the differences between Apache::URI->parse($r) and $r->parsed_uri() are very confusing use Apache::URI->parse($r) for creating a self-referential URI that needs to point to the same server

it all boils down to... the differences between Apache::URI->parse($r) and $r->parsed_uri() are very confusing use Apache::URI->parse($r) for creating a self-referential URI that needs to point to the same server use $r->parsed_uri() for accessing request attributes

Apache::Constants

Apache::Constants Apache::Constants class provides over 90 runtime constants use Apache::Constants qw(DECLINED BAD_REQUEST);

Apache::Constants Apache::Constants class provides over 90 runtime constants use Apache::Constants qw(DECLINED BAD_REQUEST); the most common are:

Apache::Constants Apache::Constants class provides over 90 runtime constants use Apache::Constants qw(DECLINED BAD_REQUEST); the most common are: OK

Apache::Constants Apache::Constants class provides over 90 runtime constants use Apache::Constants qw(DECLINED BAD_REQUEST); the most common are: OK SERVER_ERROR

Apache::Constants Apache::Constants class provides over 90 runtime constants use Apache::Constants qw(DECLINED BAD_REQUEST); the most common are: OK SERVER_ERROR REDIRECT

Apache::Constants Apache::Constants class provides over 90 runtime constants use Apache::Constants qw(DECLINED BAD_REQUEST); the most common are: OK SERVER_ERROR REDIRECT DECLINED

Return Values handlers are expected to return a value

the return value of the handler defines the status of the request

the return value of the handler defines the status of the request Apache defines three "good" return values

the return value of the handler defines the status of the request Apache defines three "good" return values OK – all is well

the return value of the handler defines the status of the request Apache defines three "good" return values OK – all is well DECLINED – forget about me

the return value of the handler defines the status of the request Apache defines three "good" return values OK – all is well DECLINED – forget about me DONE – we're finished, start to log

the return value of the handler defines the status of the request Apache defines three "good" return values OK – all is well DECLINED – forget about me DONE – we're finished, start to log All other values are "errors" and trigger the ErrorDocument cycle

When handlers turn bad...

When handlers turn bad... "error" return codes are not always errors

When handlers turn bad... "error" return codes are not always errors
instead, they indicate a new route for the request

package My::Redirect; use Apache::Constants qw(REDIRECT);
sub handler { my $r = shift; $r->headers_out->set(Location => '/foo'); return REDIRECT; }; 1;

package My::Redirect; use Apache::Constants qw(REDIRECT);
sub handler { my $r = shift; $r->headers_out->set(Location => '/foo'); return REDIRECT; }; 1; <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> <HTML><HEAD> <TITLE>302 Found</TITLE> </HEAD><BODY> <H1>Found</H1> The document has moved <A HREF="/foo">here</A>.<P> <HR> <ADDRESS>Apache/ dev Server at mainsheet.laserlink.com Port 80</ADDRESS> </BODY></HTML>

Custom Responses

Custom Responses Apache has default responses for most of the possible errors

Custom Responses Apache has default responses for most of the possible errors it also provides the ErrorDocument directive for fine-tuning server behavior

Custom Responses Apache has default responses for most of the possible errors it also provides the ErrorDocument directive for fine-tuning server behavior you can specify error behavior on-the-fly with custom_response()

custom_response()

custom_response() the custom_response() method has several interfaces...

custom_response() the custom_response() method has several interfaces... # set the response for 500 $r->custom_response(SERVER_ERROR, '/error.html')

custom_response() the custom_response() method has several interfaces... # set the response for 500 $r->custom_response(SERVER_ERROR, '/error.html') # capture the current 500 setting my $errordoc = $r->custom_response(SERVER_ERROR)

custom_response() the custom_response() method has several interfaces... # set the response for 500 $r->custom_response(SERVER_ERROR, '/error.html') # capture the current 500 setting my $errordoc = $r->custom_response(SERVER_ERROR) # reset 500 back to the Apache default $r->custom_response(SERVER_ERROR, undef);

the Apache::URI class return values and the Apache::Constants class error responses and $r‑>custom_response()

Just the Beginning

Just the Beginning almost every part of Apache's default behavior can be replaced, rewritten, or extended using mod_perl

Just the Beginning almost every part of Apache's default behavior can be replaced, rewritten, or extended using mod_perl in many cases you can do much more than you can with Apache and C due to Perl's ability to fold, spindle, and mutilate everyday items

User Authentication

User Authentication Apache default authentication mechanism is mod_auth

User Authentication Apache default authentication mechanism is mod_auth uses a password file generated using Apache's htpasswd utility

User Authentication Apache default authentication mechanism is mod_auth uses a password file generated using Apache's htpasswd utility geoff:zzpEyL0tbgwwk

User Authentication configuration placed in .htaccess file or httpd.conf

User Authentication configuration placed in .htaccess file or httpd.conf AuthUserFile .htpasswd AuthName "my site" AuthType Basic Require valid-user

Who Uses Flat Files?

Who Uses Flat Files? flat files are limiting, hard to manage, difficult to integrate, and just plain boring

Who Uses Flat Files? flat files are limiting, hard to manage, difficult to integrate, and just plain boring we can use the Apache API and Perl to replace flat files with our own authentication mechanism

How Authentication Works
client requests a document

client requests a document GET /perl-status HTTP/1.1 Accept: text/xml, image/png, image/jpeg, image/gif, text/plain Accept-Charset: ISO , utf-8;q=0.66, *;q=0.66 Accept-Encoding: gzip, deflate, compress;q=0.9 Accept-Language: en-us Connection: keep-alive Host: Keep-Alive: 300 User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US)

client requests a document GET /perl-status HTTP/1.1 Accept: text/xml, image/png, image/jpeg, image/gif, text/plain Accept-Charset: ISO , utf-8;q=0.66, *;q=0.66 Accept-Encoding: gzip, deflate, compress;q=0.9 Accept-Language: en-us Connection: keep-alive Host: Keep-Alive: 300 User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US) server denies request

client requests a document GET /perl-status HTTP/1.1 Accept: text/xml, image/png, image/jpeg, image/gif, text/plain Accept-Charset: ISO , utf-8;q=0.66, *;q=0.66 Accept-Encoding: gzip, deflate, compress;q=0.9 Accept-Language: en-us Connection: keep-alive Host: Keep-Alive: 300 User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US) server denies request HTTP/ Authorization Required WWW-Authenticate: Basic realm="my site" Keep-Alive: timeout=15, max=100 Connection: Keep-Alive Transfer-Encoding: chunked Content-Type: text/html; charset=iso

client request client request logging URI-based init content URI translation fixups file-based init MIME setting resource control

client request client request URI-based init URI translation file-based init resource control resource control

client request client request URI-based init URI translation file-based init resource control resource control HTTP/ Authorization Required

client request client request logging URI-based init URI translation file-based init resource control resource control

client sends a new request

client sends a new request GET /perl-status HTTP/1.1 Accept: text/xml, image/png, image/jpeg, image/gif, text/plain Accept-Charset: ISO , utf-8;q=0.66, *;q=0.66 Accept-Encoding: gzip, deflate, compress;q=0.9 Accept-Language: en-us Authorization: Basic Z2VvZmY6YWZha2VwYXNzd29yZA== Connection: keep-alive Host: Keep-Alive: 300 User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US)

client sends a new request GET /perl-status HTTP/1.1 Accept: text/xml, image/png, image/jpeg, image/gif, text/plain Accept-Charset: ISO , utf-8;q=0.66, *;q=0.66 Accept-Encoding: gzip, deflate, compress;q=0.9 Accept-Language: en-us Authorization: Basic Z2VvZmY6YWZha2VwYXNzd29yZA== Connection: keep-alive Host: Keep-Alive: 300 User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US) server sends document

client sends a new request GET /perl-status HTTP/1.1 Accept: text/xml, image/png, image/jpeg, image/gif, text/plain Accept-Charset: ISO , utf-8;q=0.66, *;q=0.66 Accept-Encoding: gzip, deflate, compress;q=0.9 Accept-Language: en-us Authorization: Basic Z2VvZmY6YWZha2VwYXNzd29yZA== Connection: keep-alive Host: Keep-Alive: 300 User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US) server sends document HTTP/ OK Keep-Alive: timeout=15, max=99 Connection: Keep-Alive Transfer-Encoding: chunked Content-Type: text/html

Do it in Perl since mod_perl gives us the ability to intercept the request cycle before Apache, we can authenticate using Perl instead

Do it in Perl since mod_perl gives us the ability to intercept the request cycle before Apache, we can authenticate using Perl instead Apache provides an API, making the job easy

Do it in Perl since mod_perl gives us the ability to intercept the request cycle before Apache, we can authenticate using Perl instead Apache provides an API, making the job easy mod_perl provides access to the Apache API

package My::Authenticate;
use Apache::Constants qw(OK DECLINED AUTH_REQUIRED); use strict; sub handler { my $r = shift; # Let subrequests pass. return DECLINED unless $r->is_initial_req; # Get the client-supplied credentials. my ($status, $password) = $r->get_basic_auth_pw; return $status unless $status == OK; # Perform some custom user/password validation. return OK if authenticate_user($r->user, $password); # Whoops, bad credentials. $r->note_basic_auth_failure; return AUTH_REQUIRED; }

No Authorization Header
client requests a document GET /perl-status HTTP/1.1 Accept: text/xml, image/png, image/jpeg, image/gif, text/plain Accept-Charset: ISO , utf-8;q=0.66, *;q=0.66 Accept-Encoding: gzip, deflate, compress;q=0.9 Accept-Language: en-us Connection: keep-alive Host: Keep-Alive: 300 User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US) server denies request HTTP/ Authorization Required WWW-Authenticate: Basic realm="my site" Keep-Alive: timeout=15, max=100 Connection: Keep-Alive Transfer-Encoding: chunked Content-Type: text/html; charset=iso

package My::Authenticate;
use Apache::Constants qw(OK DECLINED AUTH_REQUIRED); use strict; sub handler { my $r = shift; # Let subrequests pass. return DECLINED unless $r->is_initial_req; # Get the client-supplied credentials. my ($status, $password) = $r->get_basic_auth_pw; return $status unless $status == OK; # Perform some custom user/password validation. return OK if authenticate_user($r->user, $password); # Whoops, bad credentials. $r->note_basic_auth_failure; return AUTH_REQUIRED; }

Configuration

Configuration change AuthUserFile .htpasswd AuthName "my site"
AuthType Basic Require valid-user

Configuration change to AuthUserFile .htpasswd AuthName "my site"
AuthType Basic Require valid-user to PerlAuthenHandler My::Authenticate

The Choice is Yours how you decide to authenticate is now up to you

sub authenticate_user { my ($user, $pass) return $user eq $pass; }

sub authenticate_user { my ($user, $pass) return $user eq $pass; } are you seeing the possibilities yet?

The Power of CPAN over 25 Apache:: shrink-wrapped modules on CPAN for authentication SecureID Radius SMB LDAP NTLM

To Infinity and Beyond!

To Infinity and Beyond! this example only covered Basic authentication via popup box

To Infinity and Beyond! this example only covered Basic authentication via popup box the same techniques can be used to authenticate via a login form plus cookies, munged URLs, or hidden fields

To Infinity and Beyond! this example only covered Basic authentication via popup box the same techniques can be used to authenticate via a login form plus cookies, munged URLs, or hidden fields extended to use Digest authentication as well

Content Generation client request logging URI-based init content

Sample PerlHandler create a handler that uses CPAN module HTML::Clean to "clean" outgoing documents

Sample PerlHandler create a handler that uses CPAN module HTML::Clean to "clean" outgoing documents alter the handler to take advantage of more advanced mod_perl features

use Apache::Constants qw(OK DECLINED); use Apache::File;
package TPC::Clean; use Apache::Constants qw(OK DECLINED); use Apache::File; use HTML::Clean; use strict; sub handler { my $r = shift; my $fh = Apache::File->new($r->filename) or return DECLINED; my $dirty = do {local $/; <$fh>}; my $h = HTML::Clean->new(\$dirty); $h->level(3); $h->strip; $r->send_http_header('text/html'); print ${$h->data}; return OK; } 1;

Configuration add directives to httpd.conf to mirror DocumentRoot
Alias /clean /usr/local/apache/htdocs <Location /clean> SetHandler perl-script PerlHandler TPC::Clean </Location>

Results original: 202 bytes <html> <body>
<form method="GET" action="/foo"> Text: <input type="text" name="foo"><br> <input type="submit"> </form> <strong>hi there </strong> </body> </html>

Results original: 202 bytes clean: 145 bytes <html> <body>
<form method="GET" action="/foo"> Text: <input type="text" name="foo"><br> <input type="submit"> </form> <strong>hi there </strong> </body> </html> clean: 145 bytes <html><body><form method="GET" action="/foo"> Text: <input type="text" name="foo"><br><input type="submit"></form><b>hi there </b></body></html>

Key Concepts

Key Concepts Apache::File class

Key Concepts Apache::File class $r->filename

Key Concepts Apache::File class $r->filename local $/

Apache::File

Apache::File Apache::File is similar to IO::File

my $fh = Apache::File->new($r->filename); while (my $line = <$fh>) { ... }

my $fh = Apache::File->new($r->filename); while (my $line = <$fh>) { ... } it also adds a number of methods to the Apache class for use when manipulating files over HTTP

$r->filename()

$r->filename() contains the result of URI-to-filename translation

if you just want to stat() the requested file, use $r->finfo and the special filehandle _

if you just want to stat() the requested file, use $r->finfo and the special filehandle _ if (-f $r->finfo && -M _ < $timeout) { ... }

local $/;

local $/; typical Perl idiom

local $/; typical Perl idiom local $/; my $file = <$fh>; #slurp

local $/; typical Perl idiom local $/; my $file = <$fh>; #slurp
my $file = do {local $/; <$fh>};

local $/; typical Perl idiom bad under mod_perl local $/;
my $file = <$fh>; #slurp my $file = do {local $/; <$fh>}; bad under mod_perl

local $/; typical Perl idiom bad under mod_perl
my $file = <$fh>; #slurp my $file = do {local $/; <$fh>}; bad under mod_perl but we do it anyway with justification

The Choice is Yours!

The Choice is Yours! Content filtering with Apache::Filter?

The Choice is Yours! Content filtering with Apache::Filter?
Using proper cache-friendly headers?

Magic filtered content generation impossible with Apache 1.3

can't send CGI output through mod_ssi

can't send CGI output through mod_ssi reason for output filters in Apache 2.0

can't send CGI output through mod_ssi reason for output filters in Apache 2.0 mod_perl has had output filtering for years

can't send CGI output through mod_ssi reason for output filters in Apache 2.0 mod_perl has had output filtering for years possible due to Perl's TIEHANDLE interface

TIEHANDLE in mod_perl

TIEHANDLE in mod_perl mod_perl tie()s STDOUT to the Apache class prior to the content generation phase

TIEHANDLE in mod_perl mod_perl tie()s STDOUT to the Apache class prior to the content generation phase you can tie() STDOUT as well and override mod_perl's default behavior

TIEHANDLE in mod_perl mod_perl tie()s STDOUT to the Apache class prior to the content generation phase you can tie() STDOUT as well and override mod_perl's default behavior very useful with stacked handlers

Stacked Handlers

Stacked Handlers for each phase of the request, mod_perl will run any registered Perl handlers for that phase

Stacked Handlers for each phase of the request, mod_perl will run any registered Perl handlers for that phase you can register more than one Perl handler per phase

Stacked Handlers for each phase of the request, mod_perl will run any registered Perl handlers for that phase you can register more than one Perl handler per phase whether all handlers are called depends on the syntax of the phase itself in Apache

Stacked Handlers some phase run until the handler list is exhausted

PerlLogHandler My::DBLogger PerlLogHandler My::FileLogger

PerlLogHandler My::DBLogger PerlLogHandler My::FileLogger some phases run until one handler returns OK

PerlLogHandler My::DBLogger PerlLogHandler My::FileLogger some phases run until one handler returns OK PerlTransHandler My::TranslateHTML PerlTransHandler My::TranslateText

PerlLogHandler My::DBLogger PerlLogHandler My::FileLogger some phases run until one handler returns OK PerlTransHandler My::TranslateHTML PerlTransHandler My::TranslateText all phases terminate on "error"

Stacked Content Handlers

for the content generation phase, running multiple Perl handlers can be incredibly powerful

for the content generation phase, running multiple Perl handlers can be incredibly powerful Apache::Filter implements a simple interface for pipelining content handlers

for the content generation phase, running multiple Perl handlers can be incredibly powerful Apache::Filter implements a simple interface for pipelining content handlers uses TIEHANDLE in the background

Now for the Fun Part

Now for the Fun Part modify our handler to work either standalone or as part of a handler chain

Now for the Fun Part modify our handler to work either standalone or as part of a handler chain easy using Apache::Filter

Apache::Filter Changes

my $fh = Apache::File->new($r->filename) or return DECLINED;

my $fh = Apache::File->new($r->filename) or return DECLINED; to: my $fh = undef; if (lc $r->dir_config('Filter') eq 'on') { $r = $r->filter_register; ($fh, my $status) = $r->filter_input; return $status unless $status == OK } else { $fh = Apache::File->new($r->filename) or return NOT_FOUND;

Configuration

Configuration change Alias /clean /usr/local/apache/htdocs
<Location /clean> SetHandler perl-script PerlHandler My::Clean </Location>

Configuration change to Alias /clean /usr/local/apache/htdocs
<Location /clean> SetHandler perl-script PerlHandler My::Clean </Location> to PerlModule Apache::Filter PerlSetVar Filter On

Key Concepts Apache::Filter API

Apache::Filter

Apache::Filter Apache::Filter adds methods to the Apache class

do not have to use Apache::Filter;

do not have to use Apache::Filter; do have to PerlModule Apache::Filter

do not have to use Apache::Filter; do have to PerlModule Apache::Filter because filtering content is tricky, the interface is quirky

do not have to use Apache::Filter; do have to PerlModule Apache::Filter because filtering content is tricky, the interface is quirky $r = $r->filter_register;

Apache::Filter to get at filtered input, call $r->filter_input()

returns an open filehandle on the input stream

returns an open filehandle on the input stream if the first filter, the filehandle is for $r->filename()

returns an open filehandle on the input stream if the first filter, the filehandle is for $r->filename() all filters use the same API, regardless of their position in the chain

So What?

So What? new Apache::Filter aware code works the same as the standalone module

So What? new Apache::Filter aware code works the same as the standalone module can be used as part of a PerlHandler chain

So What? new Apache::Filter aware code works the same as the standalone module can be used as part of a PerlHandler chain can be any part of the chain

Compressing Output

Compressing Output use Apache::Compress

Compressing Output use Apache::Compress available from CPAN

uses Compress::Zlib to compress output

uses Compress::Zlib to compress output Apache::Filter aware

Configuration

Configuration change Alias /clean /usr/local/apache/htdocs
<Location /clean> SetHandler perl-script PerlHandler My::Clean PerlSetVar Filter On </Location>

Configuration change to Alias /clean /usr/local/apache/htdocs
<Location /clean> SetHandler perl-script PerlHandler My::Clean PerlSetVar Filter On </Location> to PerlHandler My::Clean Apache::Compress

Stacked Power http://perl.apache.org/index.html straight HTML
35668 bytes My::Clean 28162 bytes (79%) Apache::Compress 8177 bytes (23%) My::Clean + Apache::Compress 7458 bytes (21%)

Caveats

Caveats using Apache::Filter is actually a bit more complex than this...

Caveats using Apache::Filter is actually a bit more complex than this... see the recent version of Apache::Clean to get an idea

Cache Headers

Cache Headers we often think of dynamic content as "could be different on any given access"

Cache Headers we often think of dynamic content as "could be different on any given access" "dynamic" content can also be static with clearly defined factors that can change its meaning

Cache Headers we often think of dynamic content as "could be different on any given access" "dynamic" content can also be static with clearly defined factors that can change its meaning by properly managing HTTP/1.1 cache headers, we can reduce strain on our servers

Conditional GET Request

HTTP/1.1 allows for a conditional GET request

HTTP/1.1 allows for a conditional GET request clients are allowed to use cached content based on information about the resource

HTTP/1.1 allows for a conditional GET request clients are allowed to use cached content based on information about the resource information is provided by both the client and the server

GET /manual/index.html HTTP/1.1
Accept: text/html, image/png, image/jpeg, image/gif, image/x-xbitmap, */* Accept-Charset: windows-1252;q=1.0, utf-8;q=1.0, utf-16;q=1.0, iso ;q=0.6, *;q=0.1 Accept-Encoding: deflate, gzip, x-gzip, identity, *;q=0 Accept-Language: en Connection: Keep-Alive, TE Host: mainsheet.laserlink.net TE: deflate, gzip, chunked, identity, trailers User-Agent: Mozilla/4.0 (compatible; MSIE 5.0; Windows XP) Opera [en] HTTP/ OK Last-Modified: Thu, 01 Nov :35:27 GMT ETag: "4c be179cf" Accept-Ranges: bytes Content-Length: 9268 Connection: close Content-Type: text/html

Accept: text/html, image/png, image/jpeg, image/gif, image/x-xbitmap, */* Accept-Charset: windows-1252;q=1.0, utf-8;q=1.0, utf-16;q=1.0, iso ;q=0.6, *;q=0.1 Accept-Encoding: deflate, gzip, x-gzip, identity, *;q=0 Accept-Language: en Connection: Keep-Alive, TE Host: mainsheet.laserlink.net If-Modified-Since: Thu, 01 Nov :35:27 GMT If-None-Match: "4c be179cf TE: deflate, gzip, chunked, identity, trailers User-Agent: Mozilla/4.0 (compatible; MSIE 5.0; Windows XP) Opera [en] HTTP/ Not Modified Last-Modified: Thu, 01 Nov :35:27 GMT ETag: "4c be179cf" Accept-Ranges: bytes Connection: close

Accept: text/html, image/png, image/jpeg, image/gif, image/x-xbitmap, */* Accept-Charset: windows-1252;q=1.0, utf-8;q=1.0, utf-16;q=1.0, iso ;q=0.6, *;q=0.1 Accept-Encoding: deflate, gzip, x-gzip, identity, *;q=0 Accept-Language: en Connection: Keep-Alive, TE Host: mainsheet.laserlink.net If-Modified-Since: Thu, 01 Nov :35:27 GMT If-None-Match: "4c be179cf TE: deflate, gzip, chunked, identity, trailers User-Agent: Mozilla/4.0 (compatible; MSIE 5.0; Windows XP) Opera [en] HTTP/ OK Last-Modified: Thu, 06 Jun :51:11 GMT ETag: "4c cff4caf" Accept-Ranges: bytes Content-Length: 9268 Connection: close

for static documents, Apache takes care of making our response cache-friendly

for static documents, Apache takes care of making our response cache-friendly since the file is on disk, Apache can determine when the file was last changed

for static documents, Apache takes care of making our response cache-friendly since the file is on disk, Apache can determine when the file was last changed with static files, local modification is the only factor

for static documents, Apache takes care of making our response cache-friendly since the file is on disk, Apache can determine when the file was last changed with static files, local modification is the only factor still too many rules to keep straight

for static documents, Apache takes care of making our response cache-friendly since the file is on disk, Apache can determine when the file was last changed with static files, local modification is the only factor still too many rules to keep straight Apache provides an API to use so we don't have to think too much

Now for the Fun Part

Now for the Fun Part modify our handler to be "cache friendly"

send 304 when the document hasn't changed

send 304 when the document hasn't changed properly handle If-* header comparisons

How do you define change?

when dynamically altering static documents there are a number of factors to consider

when dynamically altering static documents there are a number of factors to consider when the file changes on disk

when dynamically altering static documents there are a number of factors to consider when the file changes on disk when the code changes

when dynamically altering static documents there are a number of factors to consider when the file changes on disk when the code changes when the options to the code changes

when dynamically altering static documents there are a number of factors to consider when the file changes on disk when the code changes when the options to the code changes all of these affect the "freshness" of the document

Code Changes

Code Changes in order to determine when the code itself changes, we need to mark the modification time of the package

Code Changes in order to determine when the code itself changes, we need to mark the modification time of the package at request time, we call an API to compare the package modification to the If-Modified-Since header

Code Changes in order to determine when the code itself changes, we need to mark the modification time of the package at request time, we call an API to compare the package modification to the If-Modified-Since header on reloads, we regenerate the package modification time

package My::Clean; use Apache::Constants qw(OK DECLINED); use Apache::File; use HTML::Clean; use strict; sub handler { my $r = shift; my $fh = Apache::File->new($r->filename) or return DECLINED; my $dirty = do {local $/; <$fh>}; my $h = HTML::Clean->new(\$dirty); $h->level(3); $h->strip; $r->send_http_header('text/html'); print ${$h->data}; return OK; } 1;

package My::Clean; use Apache::Constants qw(OK DECLINED); use Apache::File; use HTML::Clean; use strict; # Get the package modification time... (my $package = __PACKAGE__) =~ s!::!/!g; my $package_mtime = (stat $INC{"$package.pm"})[9];

Configuration Changes

in order to determine when the options to the code change, we need to mark the modification time of httpd.conf

in order to determine when the options to the code change, we need to mark the modification time of httpd.conf at request time, we call an API to compare the configuration modification to the If-Modified-Since header

in order to determine when the options to the code change, we need to mark the modification time of httpd.conf at request time, we call an API to compare the configuration modification to the If-Modified-Since header on restarts, we regenerate the configuration modification time

package My::Clean; use Apache::Constants qw(OK DECLINED); use Apache::File; use HTML::Clean; use strict; # Get the package modification time... (my $package = __PACKAGE__) =~ s!::!/!g; my $package_mtime = (stat $INC{"$package.pm"})[9];

package My::Clean; use Apache::Constants qw(OK DECLINED); use Apache::File; use HTML::Clean; use strict; # Get the package modification time... (my $package = __PACKAGE__) =~ s!::!/!g; my $package_mtime = (stat $INC{"$package.pm"})[9]; # ...and when httpd.conf was last modified my $conf_mtime = (stat Apache->server_root_relative('conf/httpd.conf'))[9]; # When the server is restarted we need to # make sure we recognize config file changes and propigate # them to the client to clear the client cache if necessary. Apache->server->register_cleanup(sub { $conf_mtime = (stat Apache->server_root_relative('conf/httpd.conf'))[9]; });

Resource Changes

Resource Changes in order to determine when the resources changes, we need to mark the modification time of $r->filename

Resource Changes in order to determine when the resources changes, we need to mark the modification time of $r->filename at request time, we call an API to compare the resource modification to the If-Modified-Since header

Resource Changes in order to determine when the resources changes, we need to mark the modification time of $r->filename at request time, we call an API to compare the resource modification to the If-Modified-Since header resource modification is checked on each request

package My::Clean; use Apache::Constants qw(OK DECLINED); use Apache::File; use HTML::Clean; use strict; # Get the package modification time... (my $package = __PACKAGE__) =~ s!::!/!g; my $package_mtime = (stat $INC{"$package.pm"})[9]; # ...and when httpd.conf was last modified my $conf_mtime = (stat Apache->server_root_relative('conf/httpd.conf'))[9]; # When the server is restarted we need to # make sure we recognize config file changes and propigate # them to the client to clear the client cache if necessary. Apache->server->register_cleanup(sub { $conf_mtime = (stat Apache->server_root_relative('conf/httpd.conf'))[9]; });

package My::Clean; use Apache::Constants qw(OK DECLINED); use Apache::File; use HTML::Clean; use strict; # Get the package modification time... (my $package = __PACKAGE__) =~ s!::!/!g; my $package_mtime = (stat $INC{"$package.pm"})[9]; # ...and when httpd.conf was last modified my $conf_mtime = (stat Apache->server_root_relative('conf/httpd.conf'))[9]; # When the server is restarted we need to # make sure we recognize config file changes and propigate # them to the client to clear the client cache if necessary. Apache->server->register_cleanup(sub { $conf_mtime = (stat Apache->server_root_relative('conf/httpd.conf'))[9]; }); sub handler { ... } 1;

my $fh = Apache::File->new($r->filename) or return DECLINED;
sub handler { my $r = shift; my $fh = Apache::File->new($r->filename) or return DECLINED; my $dirty = do {local $/; <$fh>}; my $h = HTML::Clean->new(\$dirty); $h->level(3); $h->strip; $r->send_http_header('text/html'); print ${$h->data}; return OK; }

my $fh = Apache::File->new($r->filename) or return DECLINED;
sub handler { my $r = shift; my $fh = Apache::File->new($r->filename) or return DECLINED; my $dirty = do {local $/; <$fh>}; my $h = HTML::Clean->new(\$dirty); $h->level(3); $h->strip; $r->update_mtime($package_mtime); $r->update_mtime((stat $r->finfo)[9]); $r->update_mtime($conf_mtime); $r->set_last_modified; $r->set_etag; $r->set_content_length(length ${$h->data}); # only send the file if it meets cache criteria if ((my $status = $r->meets_conditions) == OK) { $r->send_http_header('text/html'); } else { return $status; print ${$h->data}; return OK;

Key Concepts

Key Concepts Apache::File

Key Concepts Apache::File update_mtime() and time comparisons

headers to never modify directly

headers to never modify directly meets_conditions() for header comparison

Apache::File

Apache::File when you use Apache::File; methods are added to the Apache class

Apache::File when you use Apache::File; methods are added to the Apache class update_mtime() set_content_length() set_last_modified() set_etag() meets_conditions() set_byterange() each_byterange()

update_mtime()

update_mtime() used to update the apparent modification time of the resource

update_mtime() used to update the apparent modification time of the resource compares the current resource mtime to the set attempt and keeps the most recent

update_mtime() used to update the apparent modification time of the resource compares the current resource mtime to the set attempt and keeps the most recent just pile calls to update_mtime() up and let Apache do the work

Special Headers

Special Headers some headers you don't want to manipulate with headers_out()

Special Headers some headers you don't want to manipulate with headers_out() Apache provides a special set of APIs for these

Special Headers some headers you don't want to manipulate with headers_out() Apache provides a special set of APIs for these the ones added by Apache::File

set_last_modified()

set_last_modified() sets the Last-Modified header

uses mtime slot in the request record by default

uses mtime slot in the request record by default can pass it a properly formatted time

set_etag()

set_etag() sets the ETag header

set_etag() sets the ETag header
ETag is supposed to be unique for every version of a resource that ever existed

set_etag() sets the ETag header
ETag is supposed to be unique for every version of a resource that ever existed use only with static resources

set_content_length()

sets the Content-Length header

sets the Content-Length header ...

meets_conditions()

meets_conditions() does all the nasty comparisons between the client and server headers

meets_conditions() does all the nasty comparisons between the client and server headers returns OK or HTTP_NOT_MODIFIED

meets_conditions() does all the nasty comparisons between the client and server headers returns OK or HTTP_NOT_MODIFIED sets the headers_out() as appropriate

meets_conditions() does all the nasty comparisons between the client and server headers returns OK or HTTP_NOT_MODIFIED sets the headers_out() as appropriate you need to set all your outgoing headers before calling meets_conditions()

Fine Manuals Writing Apache Modules with Perl and C
mod_perl Developer's Cookbook mod_perl Pocket Reference mod_perl Guide mod_perl at the ASF

Transitioning to mod_perl Handlers

Similar presentations

Presentation on theme: "Transitioning to mod_perl Handlers"— Presentation transcript:

Similar presentations

About project

Feedback

Log in

Auth with social network:

Transitioning to mod_perl Handlers

Similar presentations

Presentation on theme: "Transitioning to mod_perl Handlers"— Presentation transcript:

Similar presentations

About project

Feedback