1docs::api::Apache2::FilUtseerr(3C)ontributed Perl Documednotcast:i:oanpi::Apache2::Filter(3)
2
3
4

NAME

6       Apache2::Filter - Perl API for Apache 2.0 Filtering
7

Synopsis

9         use Apache2::Filter ();
10
11         # filter attributes
12         my $c = $f->c;
13         my $r = $f->r;
14         my $frec = $f->frec();
15         my $next_f = $f->next;
16
17         my $ctx = $f->ctx;
18         $f->ctx($ctx);
19
20         # bucket brigade filtering API
21         $rc = $f->next->get_brigade($bb, $mode, $block, $readbytes);
22         $rc = $f->next->pass_brigade($bb);
23         $rc = $f->fflush($bb);
24
25         # streaming filtering API
26         while ($filter->read(my $buffer, $wanted)) {
27             # transform $buffer here
28             $filter->print($buffer);
29         }
30         if ($f->seen_eos) {
31             $filter->print("filter signature");
32         }
33
34         # filter manipulations
35         $r->add_input_filter(\&callback);
36         $c->add_input_filter(\&callback);
37         $r->add_output_filter(\&callback);
38         $c->add_output_filter(\&callback);
39         $f->remove;
40

Description

42       "Apache2::Filter" provides Perl API for Apache 2.0 filtering framework.
43
44       Make sure to read "the Filtering
45       tutorial|docs::2.0::user::handlers::filters".
46

Common Filter API

48       The following methods can be called from any filter handler:
49
50   "c"
51       Get the current connection object from a connection or a request
52       filter:
53
54         $c = $f->c;
55
56       obj: $f ( "Apache2::Filter object" )
57       ret: $c ( "Apache2::Connection object" )
58       since: 2.0.00
59
60   "ctx"
61       Get/set the filter context data.
62
63         $ctx = $f->ctx;
64                $f->ctx($ctx);
65
66       obj: $f ( "Apache2::Filter object" )
67       opt arg2: $ctx ( SCALAR )
68           next context
69
70       ret: $ctx ( SCALAR )
71           current context
72
73       since: 2.0.00
74
75       A filter context is created before the filter is called for the first
76       time and it's destroyed at the end of the request. The context is
77       preserved between filter invocations of the same request. So if a
78       filter needs to store some data between invocations it should use the
79       filter context for that.  The filter context is initialized with the
80       "undef" value.
81
82       The "ctx" method accepts a single SCALAR argument. Therefore if you
83       want to store any other perl datastructure you should use a reference
84       to it.
85
86       For example you can store a hash reference:
87
88         $f->ctx({ foo => 'bar' });
89
90       and then access it:
91
92         $foo = $f->ctx->{foo};
93
94       if you access the context more than once it's more efficient to copy
95       it's value before using it:
96
97         my $ctx = $f->ctx;
98         $foo = $ctx->{foo};
99
100       to avoid redundant method calls. As of this writing $ctx is not a tied
101       variable, so if you modify it need to store it at the end:
102
103         $f->ctx($ctx);
104
105       META: later we might make it a TIEd-variable interface, so it'll be
106       stored automatically.
107
108       Besides its primary purpose of storing context data across multiple
109       filter invocations, this method is also useful when used as a flag. For
110       example here is how to ensure that something happens only once during
111       the filter's life:
112
113         unless ($f->ctx) {
114             do_something_once();
115             $f->ctx(1);
116         }
117
118   "frec"
119       Get/set the "Apache2::FilterRec" (filter record) object.
120
121         $frec = $f->frec();
122
123       obj: $f ( "Apache2::Filter object" )
124       ret: $frec ( "Apache2::FilterRec object" )
125       since: 2.0.00
126
127       For example you can call "$frec->name" to get filter's name.
128
129   "next"
130       Return the "Apache2::Filter" object of the next filter in chain.
131
132         $next_f = $f->next;
133
134       obj: $f ( "Apache2::Filter object" )
135           The current filter object
136
137       ret: $next_f ( "Apache2::Filter object" )
138           The next filter object in chain
139
140       since: 2.0.00
141
142       Since Apache inserts several core filters at the end of each chain,
143       normally this method always returns an object. However if it's not a
144       mod_perl filter handler, you can call only the following methods on it:
145       "get_brigade", "pass_brigade", "c", "r", "frec" and "next". If you call
146       other methods the behavior is undefined.
147
148       The next filter can be a mod_perl one or not, it's easy to tell which
149       one is that by calling "$f->frec->name".
150
151   "r"
152       Inside an HTTP request filter retrieve the current request object:
153
154         $r = $f->r;
155
156       obj: $f ( "Apache2::Filter object" )
157       ret: $r ( "Apache2::RequestRec object" )
158       since: 2.0.00
159
160       If a sub-request adds filters, then that sub-request object is
161       associated with the filter.
162
163   "remove"
164       Remove the current filter from the filter chain (for the current
165       request or connection).
166
167         $f->remove;
168
169       obj: $f ( "Apache2::Filter object" )
170       ret: no return value
171       since: 2.0.00
172
173       Notice that you should either complete the current filter invocation
174       normally (by calling "get_brigade" or "pass_brigade" depending on the
175       filter kind) or if nothing was done, return "Apache2::Const::DECLINED"
176       and mod_perl will take care of passing the current bucket brigade
177       through unmodified to the next filter in chain.
178
179       Note: calling remove() on the very top connection filter doesn't affect
180       the filter chain due to a bug in Apache 2.0 (which may be fixed in
181       2.1). So don't use it with connection filters, till it gets fixed in
182       Apache and then make sure to require the minimum Apache version if you
183       rely on.
184
185       Remember that if the connection is "$c->keepalive" ) and the connection
186       filter is removed, it won't be added until the connection is closed.
187       Which may happen after many HTTP requests. You may want to keep the
188       filter in place and pass the data through unmodified, by returning
189       "Apache2::Const::DECLINED". If you need to reset the whole or parts of
190       the filter context between requests, use the technique based on
191       "$c->keepalives" counting.
192
193       This method works for native Apache (non-mod_perl) filters too.
194

Bucket Brigade Filter API

196       The following methods can be called from any filter, directly
197       manipulating bucket brigades:
198
199   "fflush"
200       Flush a bucket brigade down the filter stack.
201
202         $rc = $f->fflush($bb);
203
204       obj: $f ( "Apache2::Filter object" )
205           The current filter
206
207       arg1: $bb ( "Apache2::Brigade object" )
208           The brigade to flush
209
210       ret:  $rc ( "APR::Const status constant" )
211           Refer to the "pass_brigade()" entry.
212
213       excpt: "APR::Error"
214           Exceptions are thrown only when this function is called in the VOID
215           context. Refer to the "get_brigade()" entry for details.
216
217       since: 2.0.00
218
219       "fflush" is a shortcut method. So instead of doing:
220
221         my $b = APR::Bucket::flush_create($f->c->bucket_alloc);
222         $bb->insert_tail($b);
223         $f->pass_brigade($bb);
224
225       one can just write:
226
227         $f->fflush($bb);
228
229   "get_brigade"
230       This is a method to use in bucket brigade input filters. It acquires a
231       bucket brigade from the upstream input filter.
232
233         $rc = $next_f->get_brigade($bb, $mode, $block, $readbytes);
234         $rc = $next_f->get_brigade($bb, $mode, $block);
235         $rc = $next_f->get_brigade($bb, $mode)
236         $rc = $next_f->get_brigade($bb);
237
238       obj: $next_f ( "Apache2::Filter object" )
239           The next filter in the filter chain.
240
241           Inside filter handlers it's usually "$f->next". Inside protocol
242           handlers: "$c->input_filters".
243
244       arg1: $bb ( "APR::Brigade object" )
245           The original bucket brigade passed to "get_brigade()", which must
246           be empty.
247
248           Inside input filter handlers it's usually the second argument to
249           the filter handler.
250
251           Otherwise it should be created:
252
253             my $bb = APR::Brigade->new($c->pool, $c->bucket_alloc);
254
255           On return it gets populated with the next bucket brigade. That
256           brigade may contain nothing if there was no more data to read. The
257           return status tells the outcome.
258
259       opt arg2: $mode ( "Apache2::Const :input_mode constant" )
260           The filter mode in which the data should be read.
261
262           If inside the filter handler, you should normally pass the same
263           mode that was passed to the filter handler (the third argument).
264
265           At the end of this section the available modes are presented.
266
267           If the argument $mode is not passed,
268           "Apache2::Const::MODE_READBYTES" is used as a default value.
269
270       opt arg3: $block ( "APR::Const :read_type constant" )
271           You may ask the reading operation to be blocking:
272           "APR::Const::BLOCK_READ", or nonblocking:
273           "APR::Const::NONBLOCK_READ".
274
275           If inside the filter handler, you should normally pass the same
276           blocking mode argument that was passed to the filter handler (the
277           forth argument).
278
279           If the argument $block is not passed, "APR::Const::BLOCK_READ" is
280           used as a default value.
281
282       opt arg4: $readbytes ( integer )
283           How many bytes to read from the next filter.
284
285           If inside the filter handler, you may want the same number of
286           bytes, as the upstream filter, i.e. the argument that was passed to
287           the filter handler (the fifth argument).
288
289           If the argument $block is not passed, 8192 is used as a default
290           value.
291
292       ret: $rc ( "APR::Const status constant" )
293           On success, "APR::Const::SUCCESS" is returned and $bb is populated
294           (see the $bb entry).
295
296           In case of a failure -- a failure code is returned, in which case
297           normally it should be returned to the caller.
298
299           If the bottom-most filter doesn't read from the network, then
300           "Apache2::NOBODY_READ" is returned (META: need to add this
301           constant).
302
303           Inside protocol handlers the return code can also be
304           "APR::Const::EOF", which is success as well.
305
306       excpt: "APR::Error"
307           You don't have to ask for the return value. If this function is
308           called in the VOID context, e.g.:
309
310             $f->next->get_brigade($bb, $mode, $block, $readbytes);
311
312           mod_perl will do the error checking on your behalf, and if the
313           return code is not "APR::Const::SUCCESS", an "APR::Error exception"
314           will be thrown.  The only time you want to do the error checking
315           yourself, is when return codes besides "APR::Const::SUCCESS" are
316           considered as successful and you want to manage them by yourself.
317
318       since: 2.0.00
319
320       Available input filter modes (the optional second argument $mode) are:
321
322       ·   "Apache2::Const::MODE_READBYTES"
323
324           The filter should return at most readbytes data
325
326       ·   "Apache2::Const::MODE_GETLINE"
327
328           The filter should return at most one line of CRLF data.  (If a
329           potential line is too long or no CRLF is found, the filter may
330           return partial data).
331
332       ·   "Apache2::Const::MODE_EATCRLF"
333
334           The filter should implicitly eat any CRLF pairs that it sees.
335
336       ·   "Apache2::Const::MODE_SPECULATIVE"
337
338           The filter read should be treated as speculative and any returned
339           data should be stored for later retrieval in another mode.
340
341       ·   "Apache2::Const::MODE_EXHAUSTIVE"
342
343           The filter read should be exhaustive and read until it can not read
344           any more. Use this mode with extreme caution.
345
346       ·   "Apache2::Const::MODE_INIT"
347
348           The filter should initialize the connection if needed, NNTP or FTP
349           over SSL for example.
350
351       Either compile all these constants with:
352
353         use Apache2::Const -compile => qw(:input_mode);
354
355       But it's a bit more efficient to compile only those constants that you
356       need.
357
358       Example:
359
360       Here is a fragment of a filter handler, that receives a bucket brigade
361       from the upstream filter:
362
363         use Apache2::Filter ();
364         use APR::Const    -compile => qw(SUCCESS);
365         use Apache2::Const -compile => qw(OK);
366         sub filter {
367             my ($f, $bb, $mode, $block, $readbytes) = @_;
368
369             my $rc = $f->next->get_brigade($bb, $mode, $block, $readbytes);
370             return $rc unless $rc == APR::Const::SUCCESS;
371
372             # ... process $bb
373
374             return Apache2::Const::OK;
375         }
376
377       Usually arguments $mode, $block, $readbytes are the same as passed to
378       the filter itself.
379
380       You can see that in case of a failure, the handler returns immediately
381       with that failure code, which gets propagated to the downstream filter.
382
383       If you decide not check the return code, you can write it as:
384
385         sub filter {
386             my ($f, $bb, $mode, $block, $readbytes) = @_;
387
388             $f->next->get_brigade($bb, $mode, $block, $readbytes);
389
390             # ... process $bb
391
392             return Apache2::Const::OK;
393         }
394
395       and the error checking will be done on your behalf.
396
397       You will find many more examples in "the filter
398       handlers|docs::2.0::user::handlers::filters" and "the protocol
399       handlers|docs::2.0::user::handlers::protocols" tutorials.
400
401   "pass_brigade"
402       This is a method to use in bucket brigade output filters.  It passes
403       the current bucket brigade to the downstream output filter.
404
405         $rc = $next_f->pass_brigade($bb);
406
407       obj: $next_f ( "Apache2::Filter object" )
408           The next filter in the filter chain.
409
410           Inside output filter handlers it's usually "$f->next". Inside
411           protocol handlers: "$c->output_filters".
412
413       arg1: $bb ( "APR::Brigade object" )
414           The bucket brigade to pass.
415
416           Inside output filter handlers it's usually the second argument to
417           the filter handler (after potential manipulations).
418
419       ret: $rc ( "APR::Const status constant" )
420           On success, "APR::Const::SUCCESS" is returned.
421
422           In case of a failure -- a failure code is returned, in which case
423           normally it should be returned to the caller.
424
425           If the bottom-most filter doesn't write to the network, then
426           "Apache2::NOBODY_WROTE" is returned (META: need to add this
427           constant).
428
429           Also refer to the "get_brigade()" entry to see how to avoid
430           checking the errors explicitly.
431
432       excpt: "APR::Error"
433           Exceptions are thrown only when this function is called in the VOID
434           context. Refer to the "get_brigade()" entry for details.
435
436       since: 2.0.00
437
438       The caller relinquishes ownership of the brigade (i.e. it may get
439       destroyed/overwritten/etc. by the callee).
440
441       Example:
442
443       Here is a fragment of a filter handler, that passes a bucket brigade to
444       the downstream filter (after some potential processing of the buckets
445       in the bucket brigade):
446
447         use Apache2::Filter ();
448         use APR::Const    -compile => qw(SUCCESS);
449         use Apache2::Const -compile => qw(OK);
450         sub filter {
451             my ($f, $bb) = @_;
452
453             # ... process $bb
454
455             my $rc = $f->next->pass_brigade($bb);
456             return $rc unless $rc == APR::Const::SUCCESS;
457
458             return Apache2::Const::OK;
459         }
460

Streaming Filter API

462       The following methods can be called from any filter, which uses the
463       simplified streaming functionality:
464
465   "print"
466       Send the contents of $buffer to the next filter in chain (via internal
467       buffer).
468
469         $sent = $f->print($buffer);
470
471       obj: $f ( "Apache2::Filter object" )
472       arg1: $buffer ( string )
473           The data to send.
474
475       ret: $sent ( integer )
476           How many characters were sent. There is no need to check, since all
477           should go through and if something goes work an exception will be
478           thrown.
479
480       excpt: "APR::Error"
481       since: 2.0.00
482
483       This method should be used only in streaming filters.
484
485   "read"
486       Read data from the filter
487
488         $read = $f->read($buffer, $wanted);
489
490       obj: $f ( "Apache2::Filter object" )
491       arg1: $buffer ( SCALAR )
492           The buffer to fill. All previous data will be lost.
493
494       opt arg2: $wanted ( integer )
495           How many bytes to attempt to read.
496
497           If this optional argument is not specified -- the default 8192 will
498           be used.
499
500       ret: $read ( integer )
501           How many bytes were actually read.
502
503           $buffer gets populated with the string that is read. It will
504           contain an empty string if there was nothing to read.
505
506       excpt: "APR::Error"
507       since: 2.0.00
508
509       Reads at most $wanted characters into $buffer. The returned value $read
510       tells exactly how many were read, making it easy to use it in a while
511       loop:
512
513         while ($filter->read(my $buffer, $wanted)) {
514             # transform $buffer here
515             $filter->print($buffer);
516         }
517
518       This is a streaming filter method, which acquires a single bucket
519       brigade behind the scenes and reads data from all its buckets.
520       Therefore it can only read from one bucket brigade per filter
521       invocation.
522
523       If the EOS bucket is read, the "seen_eos" method will return a true
524       value.
525
526   "seen_eos"
527       This methods returns a true value when the EOS bucket is seen by the
528       "read" method.
529
530         $ok = $f->seen_eos;
531
532       obj: $f ( "Apache2::Filter object" )
533           The filter to remove
534
535       ret: $ok ( boolean )
536           a true value if EOS has been seen, otherwise a false value
537
538       since: 2.0.00
539
540       This method only works in streaming filters which exhaustively
541       "$f->read" all the incoming data in a while loop, like so:
542
543             while ($f->read(my $buffer, $wanted)) {
544                 # do something with $buffer
545             }
546             if ($f->seen_eos) {
547                 # do something
548             }
549
550       The technique in this example is useful when a streaming filter wants
551       to append something to the very end of data, or do something at the end
552       of the last filter invocation. After the EOS bucket is read, the filter
553       should expect not to be invoked again.
554
555       If an input streaming filter doesn't consume all data in the bucket
556       brigade (or even in several bucket brigades), it has to generate the
557       EOS event by itself. So when the filter is done it has to set the EOS
558       flag:
559
560         $f->seen_eos(1);
561
562       when the filter handler returns, internally mod_perl will take care of
563       creating and sending the EOS bucket to the upstream input filter.
564
565       A similar logic may apply for output filters.
566
567       In most other cases you shouldn't set this flag.  When this flag is
568       prematurely set (before the real EOS bucket has arrived) in the current
569       filter invocation, instead of invoking the filter again, mod_perl will
570       create and send the EOS bucket to the next filter, ignoring any other
571       bucket brigades that may have left to consume. As mentioned earlier
572       this special behavior is useful in writing special tests that test
573       abnormal situations.
574
576       Other methods which affect filters, but called on non-"Apache2::Filter"
577       objects:
578
579   "add_input_filter"
580       Add &callback filter handler to input request filter chain.
581
582         $r->add_input_filter(\&callback);
583
584       Add &callback filter handler to input connection filter chain.
585
586         $c->add_input_filter(\&callback);
587
588       obj: $c ( "Apache2::Connection object" ) or $r ( "Apache2::RequestRec
589       object" )
590       arg1: &callback (CODE ref)
591       ret: no return value
592       since: 2.0.00
593
594       [META: It seems that you can't add a filter when another filter is
595       called. I've tried to add an output connection filter from the input
596       connection filter when it was called for the first time. It didn't have
597       any affect for the first request (over keepalive connection). The only
598       way I succeeded to do that is from that input connection filter's
599       filter_init handler.  In fact it does work if there is any filter
600       additional filter of the same kind configured from httpd.conf or via
601       filter_init. It looks like there is a bug in httpd, where it doesn't
602       prepare the chain of 3rd party filter if none were inserted before the
603       first filter was called.]
604
605   "add_output_filter"
606       Add &callback filter handler to output request filter chain.
607
608         $r->add_output_filter(\&callback);
609
610       Add &callback filter handler to output connection filter chain.
611
612         $c->add_output_filter(\&callback);
613
614       obj: $c ( "Apache2::Connection object" ) or $r ( "Apache2::RequestRec
615       object" )
616       arg1: &callback (CODE ref)
617       ret: no return value
618       since: 2.0.00
619

Filter Handler Attributes

621       Packages using filter attributes have to subclass "Apache2::Filter":
622
623         package MyApache2::FilterCool;
624         use base qw(Apache2::Filter);
625
626       Attributes are parsed during the code compilation, by the function
627       "MODIFY_CODE_ATTRIBUTES", inherited from the "Apache2::Filter" package.
628
629   "FilterRequestHandler"
630       The "FilterRequestHandler" attribute tells mod_perl to insert the
631       filter into an HTTP request filter chain.
632
633       For example, to configure an output request filter handler, use the
634       "FilterRequestHandler" attribute in the handler subroutine's
635       declaration:
636
637         package MyApache2::FilterOutputReq;
638         sub handler : FilterRequestHandler { ... }
639
640       and add the configuration entry:
641
642         PerlOutputFilterHandler MyApache2::FilterOutputReq
643
644       This is the default mode. So if you are writing an HTTP request filter,
645       you don't have to specify this attribute.
646
647       The section HTTP Request vs. Connection Filters delves into more
648       details.
649
650   "FilterConnectionHandler"
651       The "FilterConnectionHandler" attribute tells mod_perl to insert this
652       filter into a connection filter chain.
653
654       For example, to configure an output connection filter handler, use the
655       "FilterConnectionHandler" attribute in the handler subroutine's
656       declaration:
657
658         package MyApache2::FilterOutputCon;
659         sub handler : FilterConnectionHandler { ... }
660
661       and add the configuration entry:
662
663         PerlOutputFilterHandler MyApache2::FilterOutputCon
664
665       The section HTTP Request vs. Connection Filters delves into more
666       details.
667
668   "FilterInitHandler"
669       The attribute "FilterInitHandler" marks the function suitable to be
670       used as a filter initialization callback, which is called immediately
671       after a filter is inserted to the filter chain and before it's actually
672       called.
673
674         sub init : FilterInitHandler {
675             my $f = shift;
676             #...
677             return Apache2::Const::OK;
678         }
679
680       In order to hook this filter callback, the real filter has to assign
681       this callback using the "FilterHasInitHandler" which accepts a
682       reference to the callback function.
683
684       For further discussion and examples refer to the Filter Initialization
685       Phase tutorial section.
686
687   "FilterHasInitHandler"
688       If a filter wants to run an initialization callback it can register
689       such using the "FilterHasInitHandler" attribute. Similar to
690       "push_handlers" the callback reference is expected, rather than a
691       callback name. The used callback function has to have the
692       "FilterInitHandler" attribute. For example:
693
694         package MyApache2::FilterBar;
695         use base qw(Apache2::Filter);
696         sub init   : FilterInitHandler { ... }
697         sub filter : FilterRequestHandler FilterHasInitHandler(\&init) {
698             my ($f, $bb) = @_;
699             # ...
700             return Apache2::Const::OK;
701         }
702
703       For further discussion and examples refer to the Filter Initialization
704       Phase tutorial section.
705

Configuration

707       mod_perl 2.0 filters configuration is explained in the filter handlers
708       tutorial.
709
710   "PerlInputFilterHandler"
711       See "PerlInputFilterHandler".
712
713   "PerlOutputFilterHandler"
714       See "PerlOutputFilterHandler".
715
716   "PerlSetInputFilter"
717       See "PerlSetInputFilter".
718
719   "PerlSetOutputFilter"
720       See "PerlSetInputFilter".
721

TIE Interface

723       "Apache2::Filter" also implements a tied interface, so you can work
724       with the $f object as a hash reference.
725
726       The TIE interface is mostly unimplemented and might be implemented post
727       2.0 release.
728
729   "TIEHANDLE"
730         $ret = TIEHANDLE($stashsv, $sv);
731
732       obj: $stashsv ( SCALAR )
733       arg1: $sv ( SCALAR )
734       ret: $ret ( SCALAR )
735       since: subject to change
736
737   "PRINT"
738         $ret = PRINT(...);
739
740       obj: "..." (XXX)
741       ret: $ret ( integer )
742       since: subject to change
743

See Also

745       mod_perl 2.0 documentation.
746
748       mod_perl 2.0 and its core modules are copyrighted under The Apache
749       Software License, Version 2.0.
750

Authors

752       The mod_perl development team and numerous contributors.
753
754
755
756perl v5.28.1                      2016-10-27     docs::api::Apache2::Filter(3)
Impressum