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 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 filter() method is the following:
62
63    sub filter { my ( $self, $headers, $message) = @_; ... }
64
65where $self is the filter object, $headers is a HTTP::Headers object,
66and $message is either a HTTP::Request or a HTTP::Response object.
67
68The $headers 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 $headers is
71modified by the filter, the modified headers will be sent to the
72client or server.
73
74The init() method (if it exists) is called by the new() constructeur
75to perform all initisalisation tasks. It's called once in the filter
76lifetime.
77
78A 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 HTTP::Proxy::HeaderFilter classes are lowercase.
98
99The following HeaderFilters are included in the 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 HTTP::Proxy.
110It is loaded automatically by 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 HTTP::Proxy's internals. They
120mostly are accessors.
121
122=over 4
123
124=item proxy()
125
126Gets a reference to the 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-2005, 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