[ANNOUNCE] Apache::DebugFilter 0.01_02

[Stas Bekman <st...@stason.org>]

The uploaded file

     Apache-DebugFilter-0.01_02.tar.gz

has entered CPAN as

   file: $CPAN/authors/id/S/ST/STAS/Apache-DebugFilter-0.01_02.tar.gz
   size: 5915 bytes
    md5: c7f1e8aecd5ea8deafa3515d32178351

This is a new module, which is an abstraction of a snoop filter 
(MyApache::FilterSnoop) covered here:
http://perl.apache.org/docs/2.0/user/handlers/filters.html#All_in_One_Filter

Note that it's 0.01_02, since I'm not quite sure if the API is good 
enough, so comments are welcome. Here is the README:

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 <st...@stason.org>

See Also
     http://perl.apache.org/docs/2.0/user/handlers/filters.html#All_in_One_Fi
     lter

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

     perl.


-- 
__________________________________________________________________
Stas Bekman            JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/     mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org   http://ticketmaster.com

---------------------------------------------------------------------
To unsubscribe, e-mail: announce-unsubscribe@perl.apache.org
For additional commands, e-mail: announce-help@perl.apache.org