.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "HTTP::Proxy::BodyFilter 3pm" .TH HTTP::Proxy::BodyFilter 3pm "2017-06-28" "perl v5.20.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" HTTP::Proxy::BodyFilter \- A base class for HTTP messages body filters .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& package MyFilter; \& \& use base qw( HTTP::Proxy::BodyFilter ); \& \& # a simple modification, that may break things \& sub filter { \& my ( $self, $dataref, $message, $protocol, $buffer ) = @_; \& $$dataref =~ s/PERL/Perl/g; \& } \& \& 1; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The HTTP::Proxy::BodyFilter class is used to create filters for \&\s-1HTTP\s0 request/response body data. .SS "Creating a BodyFilter" .IX Subsection "Creating a BodyFilter" A BodyFilter is just a derived class that implements some methods called by the proxy. Of all the methods presented below, only \&\f(CW\*(C`filter()\*(C'\fR \fBmust\fR be defined in the derived class. .IP "\fIfilter()\fR" 4 .IX Item "filter()" The signature of the \fIfilter()\fR method is the following: .Sp .Vb 4 \& sub filter { \& my ( $self, $dataref, $message, $protocol, $buffer ) = @_; \& ... \& } .Ve .Sp where \f(CW$self\fR is the filter object, \f(CW$dataref\fR is a reference to the chunk of body data received, \&\f(CW$message\fR is a reference to either a HTTP::Request or a HTTP::Response object, and \f(CW$protocol\fR is a reference to the LWP::Protocol protocol object. .Sp Note that this subroutine signature looks a lot like that of the call\- backs of LWP::UserAgent (except that \f(CW$message\fR is either a HTTP::Request or a HTTP::Response object). .Sp \&\f(CW$buffer\fR is a reference to a buffer where some of the unprocessed data can be stored for the next time the filter will be called (see \*(L"Using a buffer to store data for a later use\*(R" for details). Thanks to the built-in HTTP::Proxy::BodyFilter::* filters, this is rarely needed. .Sp It is possible to access the headers of the message with \&\f(CW\*(C`$message\->headers()\*(C'\fR. This HTTP::Headers object is the one that was sent to the client (if the filter is on the response stack) or origin server (if the filter is on the request stack). Modifying it in the \f(CW\*(C`filter()\*(C'\fR method is useless, since the headers have already been sent. .Sp Since \f(CW$dataref\fR is a \fIreference\fR to the data string, the referent can be modified and the changes will be transmitted through the filters that follows, until the data reaches its recipient. .Sp A HTTP::Proxy::BodyFilter object is a blessed hash, and the base class reserves only hash keys that start with \f(CW\*(C`_hpbf\*(C'\fR. .IP "\fInew()\fR" 4 .IX Item "new()" The constructor is defined for all subclasses. Initialisation tasks (if any) for subclasses should be done in the \f(CW\*(C`init()\*(C'\fR method (see below). .IP "\fIinit()\fR" 4 .IX Item "init()" This method is called by the \f(CW\*(C`new()\*(C'\fR constructeur to perform all initisalisation tasks. It's called once in the filter lifetime. .Sp It receives all the parameters passed to \f(CW\*(C`new()\*(C'\fR. .IP "\fIbegin()\fR" 4 .IX Item "begin()" Some filters might require initialisation before they are able to handle the data. If a \f(CW\*(C`begin()\*(C'\fR method is defined in your subclass, the proxy will call it before sending data to the \f(CW\*(C`filter()\*(C'\fR method. .Sp It's called once per \s-1HTTP\s0 message handled by the filter, before data processing begins. .Sp The method signature is as follows: .Sp .Vb 4 \& sub begin { \& my ( $self, $message ) = @_ \& ... \& } .Ve .IP "\fIend()\fR" 4 .IX Item "end()" Some filters might require finalisation after they are finished handling the data. If a \f(CW\*(C`end()\*(C'\fR method is defined in your subclass, the proxy will call it after it has finished sending data to the \f(CW\*(C`filter()\*(C'\fR method. .Sp It's called once per \s-1HTTP\s0 message handled by the filter, after all data processing is done. .Sp This method does not expect any parameters. .IP "\fIwill_modify()\fR" 4 .IX Item "will_modify()" This method return a boolean value that indicate if the filter will modify the body data on the fly. .Sp The default implementation returns a \fItrue\fR value. .SS "Using a buffer to store data for a later use" .IX Subsection "Using a buffer to store data for a later use" Some filters cannot handle arbitrary data: for example a filter that basically lowercases tag name will apply a simple regex such as \f(CW\*(C`s/<\es*(\ew+)([^>]*)>/<\eL$1\eE$2>/g\*(C'\fR. But the filter will fail is the chunk of data contains a tag that is cut before the final \f(CW\*(C`>\*(C'\fR. .PP It would be extremely complicated and error-prone to let each filter (and its author) do its own buffering, so the HTTP::Proxy architecture handles this too. The proxy passes to each filter, each time it is called, a reference to an empty string (\f(CW$buffer\fR in the above signature) that the filter can use to store some data for next run. .PP When the reference is \f(CW\*(C`undef\*(C'\fR, it means that the filter cannot store any data, because this is the very last run, needed to gather all the data left in all buffers. .PP It is recommended to store as little data as possible in the buffer, so as to avoid (badly) reproducing what HTTP::Proxy::BodyFilter::complete does. .PP In particular, you have to remember that all the data that remains in the buffer after the last piece of data is received from the origin server will be sent back to your filter in one big piece. .SS "The store and forward approach" .IX Subsection "The store and forward approach" HTTP::Proxy implements a \fIstore and forward\fR mechanism, for those filters which need to have the whole message body to work. It's enabled simply by pushing the HTTP::Proxy::BodyFilter::complete filter on the filter stack. .PP The data is stored in memory by the \*(L"complete\*(R" filter, which passes it on to the following filter once the full message body has been received. .SS "Standard BodyFilters" .IX Subsection "Standard BodyFilters" Standard HTTP::Proxy::BodyFilter classes are lowercase. .PP The following BodyFilters are included in the HTTP::Proxy distribution: .IP "lines" 4 .IX Item "lines" This filter makes sure that the next filter in the filter chain will only receive complete lines. The \*(L"chunks\*(R" of data received by the following filters with either end with \f(CW\*(C`\en\*(C'\fR or will be the last piece of data for the current \s-1HTTP\s0 message body. .IP "htmltext" 4 .IX Item "htmltext" This class lets you create a filter that runs a given code reference against text included in a \s-1HTML\s0 document (outside \f(CW\*(C`