1HTTP::Proxy::BodyFilterU(s3e)r Contributed Perl DocumentaHtTiToPn::Proxy::BodyFilter(3)
2
3
4

NAME

6       HTTP::Proxy::BodyFilter - A base class for HTTP messages body filters
7

SYNOPSIS

9           package MyFilter;
10
11           use base qw( HTTP::Proxy::BodyFilter );
12
13           # a simple modification, that may break things
14           sub filter {
15               my ( $self, $dataref, $message, $protocol, $buffer ) = @_;
16               $$dataref =~ s/PERL/Perl/g;
17           }
18
19           1;
20

DESCRIPTION

22       The HTTP::Proxy::BodyFilter class is used to create filters for HTTP
23       request/response body data.
24
25   Creating a BodyFilter
26       A BodyFilter is just a derived class that implements some methods
27       called by the proxy. Of all the methods presented below, only
28       "filter()" must be defined in the derived class.
29
30       filter()
31           The signature of the filter() method is the following:
32
33               sub filter {
34                   my ( $self, $dataref, $message, $protocol, $buffer ) = @_;
35                   ...
36               }
37
38           where $self is the filter object, $dataref is a reference to the
39           chunk of body data received, $message is a reference to either a
40           HTTP::Request or a HTTP::Response object, and $protocol is a
41           reference to the LWP::Protocol protocol object.
42
43           Note that this subroutine signature looks a lot like that of the
44           call- backs of LWP::UserAgent (except that $message is either a
45           HTTP::Request or a HTTP::Response object).
46
47           $buffer is a reference to a buffer where some of the unprocessed
48           data can be stored for the next time the filter will be called (see
49           "Using a buffer to store data for a later use" for details). Thanks
50           to the built-in HTTP::Proxy::BodyFilter::* filters, this is rarely
51           needed.
52
53           It is possible to access the headers of the message with
54           "$message->headers()". This HTTP::Headers object is the one that
55           was sent to the client (if the filter is on the response stack) or
56           origin server (if the filter is on the request stack). Modifying it
57           in the "filter()" method is useless, since the headers have already
58           been sent.
59
60           Since $dataref is a reference to the data string, the referent can
61           be modified and the changes will be transmitted through the filters
62           that follows, until the data reaches its recipient.
63
64           A HTTP::Proxy::BodyFilter object is a blessed hash, and the base
65           class reserves only hash keys that start with "_hpbf".
66
67       new()
68           The constructor is defined for all subclasses. Initialisation tasks
69           (if any) for subclasses should be done in the "init()" method (see
70           below).
71
72       init()
73           This method is called by the "new()" constructeur to perform all
74           initisalisation tasks. It's called once in the filter lifetime.
75
76           It receives all the parameters passed to "new()".
77
78       begin()
79           Some filters might require initialisation before they are able to
80           handle the data. If a "begin()" method is defined in your subclass,
81           the proxy will call it before sending data to the "filter()"
82           method.
83
84           It's called once per HTTP message handled by the filter, before
85           data processing begins.
86
87           The method signature is as follows:
88
89               sub begin {
90                   my ( $self, $message ) = @_
91                   ...
92               }
93
94       end()
95           Some filters might require finalisation after they are finished
96           handling the data. If a "end()" method is defined in your subclass,
97           the proxy will call it after it has finished sending data to the
98           "filter()" method.
99
100           It's called once per HTTP message handled by the filter, after all
101           data processing is done.
102
103           This method does not expect any parameters.
104
105       will_modify()
106           This method return a boolean value that indicate if the filter will
107           modify the body data on the fly.
108
109           The default implementation returns a true value.
110
111   Using a buffer to store data for a later use
112       Some filters cannot handle arbitrary data: for example a filter that
113       basically lowercases tag name will apply a simple regex such as
114       "s/<\s*(\w+)([^>]*)>/<\L$1\E$2>/g".  But the filter will fail is the
115       chunk of data contains a tag that is cut before the final ">".
116
117       It would be extremely complicated and error-prone to let each filter
118       (and its author) do its own buffering, so the HTTP::Proxy architecture
119       handles this too. The proxy passes to each filter, each time it is
120       called, a reference to an empty string ($buffer in the above signature)
121       that the filter can use to store some data for next run.
122
123       When the reference is "undef", it means that the filter cannot store
124       any data, because this is the very last run, needed to gather all the
125       data left in all buffers.
126
127       It is recommended to store as little data as possible in the buffer, so
128       as to avoid (badly) reproducing what HTTP::Proxy::BodyFilter::complete
129       does.
130
131       In particular, you have to remember that all the data that remains in
132       the buffer after the last piece of data is received from the origin
133       server will be sent back to your filter in one big piece.
134
135   The store and forward approach
136       HTTP::Proxy implements a store and forward mechanism, for those filters
137       which need to have the whole message body to work. It's enabled simply
138       by pushing the HTTP::Proxy::BodyFilter::complete filter on the filter
139       stack.
140
141       The data is stored in memory by the "complete" filter, which passes it
142       on to the following filter once the full message body has been
143       received.
144
145   Standard BodyFilters
146       Standard HTTP::Proxy::BodyFilter classes are lowercase.
147
148       The following BodyFilters are included in the HTTP::Proxy distribution:
149
150       lines
151           This filter makes sure that the next filter in the filter chain
152           will only receive complete lines. The "chunks" of data received by
153           the following filters with either end with "\n" or will be the last
154           piece of data for the current HTTP message body.
155
156       htmltext
157           This class lets you create a filter that runs a given code
158           reference against text included in a HTML document (outside
159           "<script>" and "<style>" tags). HTML entities are not included in
160           the text.
161
162       htmlparser
163           Creates a filter from a HTML::Parser object.
164
165       simple
166           This class lets you create a simple body filter from a code
167           reference.
168
169       save
170           Store the message body to a file.
171
172       complete
173           This filter stores the whole message body in memory, thus allowing
174           some actions to be taken only when the full page has been received
175           by the proxy.
176
177       tags
178           The HTTP::Proxy::BodyFilter::tags filter makes sure that the next
179           filter in the filter chain will only receive complete tags. The
180           current implementation is not 100% perfect, though.
181
182       Please read each filter's documentation for more details about their
183       use.
184

USEFUL METHODS FOR SUBCLASSES

186       Some methods are available to filters, so that they can eventually use
187       the little knowledge they might have of HTTP::Proxy's internals. They
188       mostly are accessors.
189
190       proxy()
191           Gets a reference to the HTTP::Proxy objects that owns the filter.
192           This gives access to some of the proxy methods.
193

AUTHOR

195       Philippe "BooK" Bruhat, <book@cpan.org>.
196

SEE ALSO

198       HTTP::Proxy, HTTP::Proxy::HeaderFilter.
199
201       Copyright 2003-2015, Philippe Bruhat.
202

LICENSE

204       This module is free software; you can redistribute it or modify it
205       under the same terms as Perl itself.
206
207
208
209perl v5.32.1                      2021-01-27        HTTP::Proxy::BodyFilter(3)
Impressum