/ 
Apache-DebugFilter-0.01_02
/ Apache::DebugFilter

NAME

Apache::DebugFilter - Debug mod_perl and native Apache2 filters

Synopsis

# httpd.conf
# ----------
PerlModule Apache::DebugFilter
# Connection snooping (everything)
PerlInputFilterHandler  Apache::DebugFilter::snoop_connection
PerlOutputFilterHandler Apache::DebugFilter::snoop_connection

# HTTP Request snooping (only HTTP request body)
<Location /foo>
    PerlInputFilterHandler  Apache::DebugFilter::snoop_request
    PerlOutputFilterHandler Apache::DebugFilter::snoop_request
</Location>

# in handlers
#------------
use Apache::DebugFilter;
# convert bb to an array of bucket_type => data pairs
my $ra_data = Apache::DebugFilter::bb_dump($bb);
while (my($btype, $data) = splice @data, 0, 2) {
    print "$btype => $data\n";
}

# dump pretty formatted bb's content to a filehandle of your choice
bb_dump($bb, \*STDERR);

Filter Handlers

snoop_connection()

The snoop_connection() filter handler snoops on request and response data flow. For example if the HTTP protocol request is filtered it'll show both the headers and the body of the request and response.

Notice that in order to see request's input body, the response handler must consume it.

The same handler is used for input and output filtering. It internally figures out what kind of stream it's working on.

To configure the input snooper, add to the top level server or virtual host configuration in httpd.conf:

PerlInputFilterHandler  Apache::DebugFilter::snoop_connection

To snoop on response output, add:

PerlOutputFilterHandler Apache::DebugFilter::snoop_connection

Both can be configured at the same time.

If you want to snoop on what an output filter MyApache::Filter::output does, put the snooper filter after it:

PerlOutputFilterHandler MyApache::Filter::output
PerlOutputFilterHandler Apache::DebugFilter::snoop_connection

On the contrary, to snoop on what an input filter MyApache::Filter::input does, put the snooper filter before it:

PerlInputFilterHandler Apache::DebugFilter::snoop_connection
PerlInputFilterHandler MyApache::Filter::input

This is because snoop_connection is going to be invoked first and immediately call MyApache::Filter::input the input filter for data. Only when the latter returns, snoop_connection will do its work.

snoop_request()

The snoop_request() filter handler snoops only on HTTP request and response bodies. Otherwise it's similar to snoop_connection(). Only normally it's configured for a specific <Location>. For example:

<Location /foo>
    PerlInputFilterHandler  Apache::DebugFilter::snoop_request
    PerlOutputFilterHandler Apache::DebugFilter::snoop_request
</Location>

Functions

bb_dump()

my $ra_data = Apache::DebugFilter::bb_dump($bb);

If only a bucket brigade $bb is passed, bb_dump will convert bb to an array of bucket_type => data pairs, and return a reference to it. This later can be used as in the following example:

while (my($btype, $data) = splice @$ra_data, 0, 2) {
    print "$btype => $data\n";
}

If the second argument (expected to be an open filehandle) is passed, as in:

Apache::DebugFilter::bb_dump($bb, \*STDERR);

bb_dump will print pretty formatted bb's content to that filehandle.

Author

Stas Bekman <stas@stason.org>

See Also

http://perl.apache.org/docs/2.0/user/handlers/filters.html#All_in_One_Filter

http://perl.apache.org/docs/2.0/

perl.