1 // Copyright 2014 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
5 // Filter performs filtering on data streams. Sample usage:
7 // IStream* pre_filter_source;
9 // Filter* filter = Filter::Factory(filter_type, size);
10 // int pre_filter_data_len = filter->stream_buffer_size();
11 // pre_filter_source->read(filter->stream_buffer(), pre_filter_data_len);
13 // filter->FlushStreamBuffer(pre_filter_data_len);
15 // char post_filter_buf[kBufferSize];
16 // int post_filter_data_len = kBufferSize;
17 // filter->ReadFilteredData(post_filter_buf, &post_filter_data_len);
19 // To filter a data stream, the caller first gets filter's stream_buffer_
20 // through its accessor and fills in stream_buffer_ with pre-filter data, next
21 // calls FlushStreamBuffer to notify Filter, then calls ReadFilteredData
22 // repeatedly to get all the filtered data. After all data have been filtered
23 // and read out, the caller may fill in stream_buffer_ again. This
24 // WriteBuffer-Flush-Read cycle is repeated until reaching the end of data
27 // A return of FILTER_OK from ReadData() means that more data is
28 // available to a future ReadData() call and data may not be written
29 // into stream_buffer(). A return of FILTER_NEED_MORE_DATA from ReadData()
30 // indicates that no data will be forthcoming from the filter until
31 // it receives more input data, and that the buffer at
32 // stream_buffer() may be written to.
34 // The filter being complete (no more data to provide) may be indicated
35 // by either returning FILTER_DONE or by returning FILTER_OK and indicating
36 // zero bytes output; consumers understand both those signals. Consumers
37 // are responsible for not calling ReadData() on a filter after one of these
38 // signals have been returned. Note that some filters may never signal that
39 // they are done (e.g. a pass-through filter will always
40 // say FILTER_NEED_MORE_DATA), so the consumer will also need to
41 // recognize the state of |no_more_input_data_available &&
42 // filter->stream_data_len() == 0| as FILTER_DONE.
44 // The lifetime of a Filter instance is completely controlled by its caller.
46 #ifndef NET_FILTER_FILTER_H__
47 #define NET_FILTER_FILTER_H__
52 #include "base/basictypes.h"
53 #include "base/gtest_prod_util.h"
54 #include "base/memory/ref_counted.h"
55 #include "base/memory/scoped_ptr.h"
56 #include "base/time/time.h"
57 #include "net/base/net_export.h"
63 class URLRequestContext;
66 //------------------------------------------------------------------------------
67 // Define an interface class that allows access to contextual information
68 // supplied by the owner of this filter. In the case where there are a chain of
69 // filters, there is only one owner of all the chained filters, and that context
70 // is passed to the constructor of all those filters. To be clear, the context
71 // does NOT reflect the position in a chain, or the fact that there are prior
72 // or later filters in a chain.
73 class NET_EXPORT_PRIVATE FilterContext {
75 // Enum to control what histograms are emitted near end-of-life of this
77 enum StatisticSelector {
80 SDCH_EXPERIMENT_DECODE,
81 SDCH_EXPERIMENT_HOLDBACK,
84 virtual ~FilterContext();
86 // What mime type was specified in the header for this data?
87 // Only makes senses for some types of contexts, and returns false
88 // when not applicable.
89 virtual bool GetMimeType(std::string* mime_type) const = 0;
91 // What URL was used to access this data?
92 // Return false if gurl is not present.
93 virtual bool GetURL(GURL* gurl) const = 0;
95 // What Content-Disposition header came with this data?
96 // Return false if no header was present.
97 virtual bool GetContentDisposition(std::string* disposition) const = 0;
99 // When was this data requested from a server?
100 virtual base::Time GetRequestTime() const = 0;
102 // Is data supplied from cache, or fresh across the net?
103 virtual bool IsCachedContent() const = 0;
105 // Is this a download?
106 virtual bool IsDownload() const = 0;
108 // Was this data flagged as a response to a request with an SDCH dictionary?
109 virtual bool SdchResponseExpected() const = 0;
111 // How many bytes were read from the net or cache so far (and potentially
112 // pushed into a filter for processing)?
113 virtual int64 GetByteReadCount() const = 0;
115 // What response code was received with the associated network transaction?
116 // For example: 200 is ok. 4xx are error codes. etc.
117 virtual int GetResponseCode() const = 0;
119 // The URLRequestContext associated with the request.
120 virtual const URLRequestContext* GetURLRequestContext() const = 0;
122 // The following method forces the context to emit a specific set of
123 // statistics as selected by the argument.
124 virtual void RecordPacketStats(StatisticSelector statistic) const = 0;
127 //------------------------------------------------------------------------------
128 class NET_EXPORT_PRIVATE Filter {
130 // Return values of function ReadFilteredData.
132 // Read filtered data successfully
134 // Read filtered data successfully, and the data in the buffer has been
135 // consumed by the filter, but more data is needed in order to continue
136 // filtering. At this point, the caller is free to reuse the filter
137 // buffer to provide more data.
138 FILTER_NEED_MORE_DATA,
139 // Read filtered data successfully, and filter reaches the end of the data
142 // There is an error during filtering.
146 // Specifies type of filters that can be created.
150 FILTER_TYPE_GZIP_HELPING_SDCH, // Gzip possible, but pass through allowed.
152 FILTER_TYPE_SDCH_POSSIBLE, // Sdch possible, but pass through allowed.
153 FILTER_TYPE_UNSUPPORTED,
158 // Creates a Filter object.
159 // Parameters: Filter_types specifies the type of filter created;
160 // filter_context allows filters to acquire additional details needed for
161 // construction and operation, such as a specification of requisite input
163 // If success, the function returns the pointer to the Filter object created.
164 // If failed or a filter is not needed, the function returns NULL.
166 // Note: filter_types is an array of filter types (content encoding types as
167 // provided in an HTTP header), which will be chained together serially to do
168 // successive filtering of data. The types in the vector are ordered based on
169 // encoding order, and the filters are chained to operate in the reverse
170 // (decoding) order. For example, types[0] = FILTER_TYPE_SDCH,
171 // types[1] = FILTER_TYPE_GZIP will cause data to first be gunzip filtered,
172 // and the resulting output from that filter will be sdch decoded.
173 static Filter* Factory(const std::vector<FilterType>& filter_types,
174 const FilterContext& filter_context);
176 // A simpler version of Factory() which creates a single, unchained
177 // Filter of type FILTER_TYPE_GZIP, or NULL if the filter could not be
179 static Filter* GZipFactory();
181 // External call to obtain data from this filter chain. If ther is no
182 // next_filter_, then it obtains data from this specific filter.
183 FilterStatus ReadData(char* dest_buffer, int* dest_len);
185 // Returns a pointer to the stream_buffer_.
186 IOBuffer* stream_buffer() const { return stream_buffer_.get(); }
188 // Returns the maximum size of stream_buffer_ in number of chars.
189 int stream_buffer_size() const { return stream_buffer_size_; }
191 // Returns the total number of chars remaining in stream_buffer_ to be
194 // If the function returns 0 then all data has been filtered, and the caller
195 // is safe to copy new data into stream_buffer_.
196 int stream_data_len() const { return stream_data_len_; }
198 // Flushes stream_buffer_ for next round of filtering. After copying data to
199 // stream_buffer_, the caller should call this function to notify Filter to
200 // start filtering. Then after this function is called, the caller can get
201 // post-filtered data using ReadFilteredData. The caller must not write to
202 // stream_buffer_ and call this function again before stream_buffer_ is
203 // emptied out by ReadFilteredData.
205 // The input stream_data_len is the length (in number of chars) of valid
206 // data in stream_buffer_. It can not be greater than stream_buffer_size_.
207 // The function returns true if success, and false otherwise.
208 bool FlushStreamBuffer(int stream_data_len);
210 // Translate the text of a filter name (from Content-Encoding header) into a
212 static FilterType ConvertEncodingToType(const std::string& filter_type);
214 // Given a array of encoding_types, try to do some error recovery adjustment
215 // to the list. This includes handling known bugs in the Apache server (where
216 // redundant gzip encoding is specified), as well as issues regarding SDCH
217 // encoding, where various proxies and anti-virus products modify or strip the
218 // encodings. These fixups require context, which includes whether this
219 // response was made to an SDCH request (i.e., an available dictionary was
220 // advertised in the GET), as well as the mime type of the content.
221 static void FixupEncodingTypes(const FilterContext& filter_context,
222 std::vector<FilterType>* encoding_types);
225 friend class GZipUnitTest;
226 friend class SdchFilterChainingTest;
227 FRIEND_TEST_ALL_PREFIXES(FilterTest, ThreeFilterChain);
231 // Filters the data stored in stream_buffer_ and writes the output into the
232 // dest_buffer passed in.
234 // Upon entry, *dest_len is the total size (in number of chars) of the
235 // destination buffer. Upon exit, *dest_len is the actual number of chars
236 // written into the destination buffer.
238 // This function will fail if there is no pre-filter data in the
239 // stream_buffer_. On the other hand, *dest_len can be 0 upon successful
240 // return. For example, a decoding filter may process some pre-filter data
241 // but not produce output yet.
242 virtual FilterStatus ReadFilteredData(char* dest_buffer, int* dest_len) = 0;
244 // Copy pre-filter data directly to destination buffer without decoding.
245 FilterStatus CopyOut(char* dest_buffer, int* dest_len);
247 FilterStatus last_status() const { return last_status_; }
249 // Buffer to hold the data to be filtered (the input queue).
250 scoped_refptr<IOBuffer> stream_buffer_;
252 // Maximum size of stream_buffer_ in number of chars.
253 int stream_buffer_size_;
255 // Pointer to the next data in stream_buffer_ to be filtered.
256 char* next_stream_data_;
258 // Total number of remaining chars in stream_buffer_ to be filtered.
259 int stream_data_len_;
262 // Allocates and initializes stream_buffer_ and stream_buffer_size_.
263 void InitBuffer(int size);
265 // A factory helper for creating filters for within a chain of potentially
266 // multiple encodings. If a chain of filters is created, then this may be
267 // called multiple times during the filter creation process. In most simple
268 // cases, this is only called once. Returns NULL and cleans up (deleting
269 // filter_list) if a new filter can't be constructed.
270 static Filter* PrependNewFilter(FilterType type_id,
271 const FilterContext& filter_context,
273 Filter* filter_list);
275 // Helper methods for PrependNewFilter. If initialization is successful,
276 // they return a fully initialized Filter. Otherwise, return NULL.
277 static Filter* InitGZipFilter(FilterType type_id, int buffer_size);
278 static Filter* InitSdchFilter(FilterType type_id,
279 const FilterContext& filter_context,
282 // Helper function to empty our output into the next filter's input.
283 void PushDataIntoNextFilter();
285 // Constructs a filter with an internal buffer of the given size.
286 // Only meant to be called by unit tests that need to control the buffer size.
287 static Filter* FactoryForTests(const std::vector<FilterType>& filter_types,
288 const FilterContext& filter_context,
291 // An optional filter to process output from this filter.
292 scoped_ptr<Filter> next_filter_;
293 // Remember what status or local filter last returned so we can better handle
295 FilterStatus last_status_;
297 DISALLOW_COPY_AND_ASSIGN(Filter);
302 #endif // NET_FILTER_FILTER_H__