1package HTTP::Proxy::HeaderFilter; 2 3use strict; 4use Carp; 5 6sub new { 7 my $class = shift; 8 my $self = bless {}, $class; 9 $self->init(@_) if $self->can('init'); 10 return $self; 11} 12 13sub filter { 14 croak "HTTP::Proxy::HeaderFilter cannot be used as a filter"; 15} 16 17sub proxy { 18 my ( $self, $new ) = @_; 19 return $new ? $self->{_hphf_proxy} = $new : $self->{_hphf_proxy}; 20} 21 221; 23 24__END__ 25 26=head1 NAME 27 28HTTP::Proxy::HeaderFilter - A base class for HTTP message header filters 29 30=head1 SYNOPSIS 31 32 package MyFilter; 33 34 use base qw( HTTP::Proxy::HeaderFilter ); 35 36 # changes the User-Agent header in all requests 37 # this filter must be pushed on the request stack 38 sub filter { 39 my ( $self, $headers, $message ) = @_; 40 41 $message->headers->header( User_Agent => 'MyFilter/1.0' ); 42 } 43 44 1; 45 46=head1 DESCRIPTION 47 48The L<HTTP::Proxy::HeaderFilter> class is used to create filters for 49HTTP request/response headers. 50 51=head2 Creating a HeaderFilter 52 53A HeaderFilter is just a derived class that implements some methods 54called by the proxy. Of all the methods presented below, only 55C<filter()> B<must> be defined in the derived class. 56 57=over 4 58 59=item filter() 60 61The signature of the C<filter()> method is the following: 62 63 sub filter { my ( $self, $headers, $message) = @_; ... } 64 65where C<$self> is the filter object, C<$headers> is a L<HTTP::Headers> object, 66and $message is either a L<HTTP::Request> or a L<HTTP::Response> object. 67 68The $headers L<HTTP::Headers> object is the one that will be sent to 69the client (if the filter is on the response stack) or origin 70server (if the filter is on the request stack). If C<$headers> is 71modified by the filter, the modified headers will be sent to the 72client or server. 73 74The C<init()> method (if it exists) is called by the C<new()> constructeur 75to perform all initisalisation tasks. It's called once in the filter 76lifetime. 77 78A L<HTTP::Proxy::HeaderFilter> object is a blessed hash, and the base class 79reserves only hash keys that start with C<_hphf>. 80 81=item new() 82 83The constructor is defined for all subclasses. Initialisation tasks 84(if any) for subclasses should be done in the C<init()> method (see below). 85 86=item init() 87 88This method is called by the C<new()> constructeur to perform all 89initisalisation tasks. It's called once in the filter lifetime. 90 91It receives all the parameters passed to C<new()>. 92 93=back 94 95=head2 Standard HeaderFilters 96 97Standard L<HTTP::Proxy::HeaderFilter> classes are lowercase. 98 99The following HeaderFilters are included in the L<HTTP::Proxy> distribution: 100 101=over 4 102 103=item simple 104 105This class lets you create a simple header filter from a code reference. 106 107=item standard 108 109This is the filter that provides standard headers handling for L<HTTP::Proxy>. 110It is loaded automatically by L<HTTP::Proxy>. 111 112=back 113 114Please read each filter's documentation for more details about their use. 115 116=head1 USEFUL METHODS FOR SUBCLASSES 117 118Some methods are available to filters, so that they can eventually use 119the little knowledge they might have of L<HTTP::Proxy>'s internals. They 120mostly are accessors. 121 122=over 4 123 124=item proxy() 125 126Gets a reference to the L<HTTP::Proxy> objects that owns the filter. 127This gives access to some of the proxy methods. 128 129=back 130 131=head1 AUTHOR 132 133Philippe "BooK" Bruhat, E<lt>book@cpan.orgE<gt>. 134 135=head1 SEE ALSO 136 137L<HTTP::Proxy>, L<HTTP::Proxy::BodyFilter>. 138 139=head1 COPYRIGHT 140 141Copyright 2003-2013, Philippe Bruhat. 142 143=head1 LICENSE 144 145This module is free software; you can redistribute it or modify it under 146the same terms as Perl itself. 147 148=cut 149 150