1package HTTP::Proxy::BodyFilter::complete;
2
3use strict;
4use HTTP::Proxy;
5use HTTP::Proxy::BodyFilter;
6use vars qw( @ISA );
7@ISA = qw( HTTP::Proxy::BodyFilter );
8use Carp;
9
10sub filter {
11    my ( $self, $dataref, $message, $protocol, $buffer ) = @_;
12    return unless defined $buffer;
13
14    $$buffer  = $$dataref;
15    $$dataref = "";
16}
17
18sub will_modify { 0 }
19
201;
21
22__END__
23
24=head1 NAME
25
26HTTP::Proxy::BodyFilter::complete - A filter that passes on a complete body or nothing
27
28=head1 SYNOPSIS
29
30    use HTTP::Proxy;
31    use HTTP::Proxy::BodyFilter::simple;
32    use HTTP::Proxy::BodyFilter::complete;
33
34    my $proxy = HTTP::Proxy->new;
35
36    # pass the complete response body to our filter (in one pass)
37    $proxy->push_filter(
38        mime => 'text/html',
39        response => HTTP::Proxy::BodyFilter::complete->new,
40        response => HTTP::Proxy::BodyFilter::simple->new(
41            sub {
42                my ( $self, $dataref, $message, $protocol, $buffer ) = @_;
43                # some complex processing that needs
44                # the whole response body
45            }
46        );
47    );
48
49    $proxy->start;
50
51=head1 DESCRIPTION
52
53The L<HTTP::Proxy::BodyFilter::complete> filter will ensure that the next
54filter in the filter chain will only receive complete message bodies
55(either request or response).
56
57It will store the chunks of data as they arrive, only to pass the B<entire>
58message body after the whole message has been received by the proxy.
59
60Subsequent filters is the chain will receive the whole body as a big
61piece of data.
62
63=head1 CAVEAT EMPTOR
64
65This consumes memory and time.
66
67Use with caution, otherwise your client will timeout, or your proxy will
68run out of memory.
69
70Also note that all filters after C<complete> are still called when the
71proxy receives data: they just receive empty data. They will receive
72the complete data when the filter chain is called for the very last time
73(the C<$buffer> parameter is C<undef>). (See the documentation of
74L<HTTP::Proxy::BodyFilter> for details about the C<$buffer> parameter.)
75
76=head1 METHOD
77
78This filter defines two methods, called automatically:
79
80=over 4
81
82=item filter()
83
84Stores the incoming data in memory until the last moment and passes
85empty data to the subsequent filters in the chain. They will receive
86the full body during the last round of filter calls.
87
88=item will_modify()
89
90This method returns a I<false> value, thus indicating to the system
91that it will not modify data passing through.
92
93=back
94
95=head1 AUTHOR
96
97Philippe "BooK" Bruhat, E<lt>book@cpan.orgE<gt>.
98
99=head1 THANKS
100
101Thanks to Simon Cozens and Merijn H. Brandt, who needed this almost at
102the same time. C<;-)>
103
104=head1 COPYRIGHT
105
106Copyright 2004-2013, Philippe Bruhat.
107
108=head1 LICENSE
109
110This module is free software; you can redistribute it or modify it under
111the same terms as Perl itself.
112
113=cut
114
115