Updating trunk VERSION from 2139.0 to 2140.0
[chromium-blink-merge.git] / net / http / http_cache_transaction.h
blob37fcdefdad3fc6cd1f2ee1979cb4c5f975735cfa
1 // Copyright (c) 2012 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 // This file declares HttpCache::Transaction, a private class of HttpCache so
6 // it should only be included by http_cache.cc
8 #ifndef NET_HTTP_HTTP_CACHE_TRANSACTION_H_
9 #define NET_HTTP_HTTP_CACHE_TRANSACTION_H_
11 #include <string>
13 #include "base/time/time.h"
14 #include "net/base/completion_callback.h"
15 #include "net/base/net_log.h"
16 #include "net/base/request_priority.h"
17 #include "net/http/http_cache.h"
18 #include "net/http/http_request_headers.h"
19 #include "net/http/http_response_info.h"
20 #include "net/http/http_transaction.h"
22 namespace net {
24 class PartialData;
25 struct HttpRequestInfo;
26 struct LoadTimingInfo;
28 // This is the transaction that is returned by the HttpCache transaction
29 // factory.
30 class HttpCache::Transaction : public HttpTransaction {
31 public:
32 // The transaction has the following modes, which apply to how it may access
33 // its cache entry.
35 // o If the mode of the transaction is NONE, then it is in "pass through"
36 // mode and all methods just forward to the inner network transaction.
38 // o If the mode of the transaction is only READ, then it may only read from
39 // the cache entry.
41 // o If the mode of the transaction is only WRITE, then it may only write to
42 // the cache entry.
44 // o If the mode of the transaction is READ_WRITE, then the transaction may
45 // optionally modify the cache entry (e.g., possibly corresponding to
46 // cache validation).
48 // o If the mode of the transaction is UPDATE, then the transaction may
49 // update existing cache entries, but will never create a new entry or
50 // respond using the entry read from the cache.
51 enum Mode {
52 NONE = 0,
53 READ_META = 1 << 0,
54 READ_DATA = 1 << 1,
55 READ = READ_META | READ_DATA,
56 WRITE = 1 << 2,
57 READ_WRITE = READ | WRITE,
58 UPDATE = READ_META | WRITE, // READ_WRITE & ~READ_DATA
61 Transaction(RequestPriority priority,
62 HttpCache* cache);
63 virtual ~Transaction();
65 Mode mode() const { return mode_; }
67 const std::string& key() const { return cache_key_; }
69 // Writes |buf_len| bytes of meta-data from the provided buffer |buf|. to the
70 // HTTP cache entry that backs this transaction (if any).
71 // Returns the number of bytes actually written, or a net error code. If the
72 // operation cannot complete immediately, returns ERR_IO_PENDING, grabs a
73 // reference to the buffer (until completion), and notifies the caller using
74 // the provided |callback| when the operation finishes.
76 // The first time this method is called for a given transaction, previous
77 // meta-data will be overwritten with the provided data, and subsequent
78 // invocations will keep appending to the cached entry.
80 // In order to guarantee that the metadata is set to the correct entry, the
81 // response (or response info) must be evaluated by the caller, for instance
82 // to make sure that the response_time is as expected, before calling this
83 // method.
84 int WriteMetadata(IOBuffer* buf,
85 int buf_len,
86 const CompletionCallback& callback);
88 // This transaction is being deleted and we are not done writing to the cache.
89 // We need to indicate that the response data was truncated. Returns true on
90 // success. Keep in mind that this operation may have side effects, such as
91 // deleting the active entry.
92 bool AddTruncatedFlag();
94 HttpCache::ActiveEntry* entry() { return entry_; }
96 // Returns the LoadState of the writer transaction of a given ActiveEntry. In
97 // other words, returns the LoadState of this transaction without asking the
98 // http cache, because this transaction should be the one currently writing
99 // to the cache entry.
100 LoadState GetWriterLoadState() const;
102 const CompletionCallback& io_callback() { return io_callback_; }
104 const BoundNetLog& net_log() const;
106 // Bypasses the cache lock whenever there is lock contention.
107 void BypassLockForTest() {
108 bypass_lock_for_test_ = true;
111 // HttpTransaction methods:
112 virtual int Start(const HttpRequestInfo* request_info,
113 const CompletionCallback& callback,
114 const BoundNetLog& net_log) OVERRIDE;
115 virtual int RestartIgnoringLastError(
116 const CompletionCallback& callback) OVERRIDE;
117 virtual int RestartWithCertificate(
118 X509Certificate* client_cert,
119 const CompletionCallback& callback) OVERRIDE;
120 virtual int RestartWithAuth(const AuthCredentials& credentials,
121 const CompletionCallback& callback) OVERRIDE;
122 virtual bool IsReadyToRestartForAuth() OVERRIDE;
123 virtual int Read(IOBuffer* buf,
124 int buf_len,
125 const CompletionCallback& callback) OVERRIDE;
126 virtual void StopCaching() OVERRIDE;
127 virtual bool GetFullRequestHeaders(
128 HttpRequestHeaders* headers) const OVERRIDE;
129 virtual int64 GetTotalReceivedBytes() const OVERRIDE;
130 virtual void DoneReading() OVERRIDE;
131 virtual const HttpResponseInfo* GetResponseInfo() const OVERRIDE;
132 virtual LoadState GetLoadState() const OVERRIDE;
133 virtual UploadProgress GetUploadProgress(void) const OVERRIDE;
134 virtual void SetQuicServerInfo(QuicServerInfo* quic_server_info) OVERRIDE;
135 virtual bool GetLoadTimingInfo(
136 LoadTimingInfo* load_timing_info) const OVERRIDE;
137 virtual void SetPriority(RequestPriority priority) OVERRIDE;
138 virtual void SetWebSocketHandshakeStreamCreateHelper(
139 net::WebSocketHandshakeStreamBase::CreateHelper* create_helper) OVERRIDE;
140 virtual void SetBeforeNetworkStartCallback(
141 const BeforeNetworkStartCallback& callback) OVERRIDE;
142 virtual void SetBeforeProxyHeadersSentCallback(
143 const BeforeProxyHeadersSentCallback& callback) OVERRIDE;
144 virtual int ResumeNetworkStart() OVERRIDE;
146 private:
147 static const size_t kNumValidationHeaders = 2;
148 // Helper struct to pair a header name with its value, for
149 // headers used to validate cache entries.
150 struct ValidationHeaders {
151 ValidationHeaders() : initialized(false) {}
153 std::string values[kNumValidationHeaders];
154 bool initialized;
157 enum State {
158 STATE_NONE,
159 STATE_GET_BACKEND,
160 STATE_GET_BACKEND_COMPLETE,
161 STATE_SEND_REQUEST,
162 STATE_SEND_REQUEST_COMPLETE,
163 STATE_SUCCESSFUL_SEND_REQUEST,
164 STATE_NETWORK_READ,
165 STATE_NETWORK_READ_COMPLETE,
166 STATE_INIT_ENTRY,
167 STATE_OPEN_ENTRY,
168 STATE_OPEN_ENTRY_COMPLETE,
169 STATE_CREATE_ENTRY,
170 STATE_CREATE_ENTRY_COMPLETE,
171 STATE_DOOM_ENTRY,
172 STATE_DOOM_ENTRY_COMPLETE,
173 STATE_ADD_TO_ENTRY,
174 STATE_ADD_TO_ENTRY_COMPLETE,
175 STATE_START_PARTIAL_CACHE_VALIDATION,
176 STATE_COMPLETE_PARTIAL_CACHE_VALIDATION,
177 STATE_UPDATE_CACHED_RESPONSE,
178 STATE_UPDATE_CACHED_RESPONSE_COMPLETE,
179 STATE_OVERWRITE_CACHED_RESPONSE,
180 STATE_TRUNCATE_CACHED_DATA,
181 STATE_TRUNCATE_CACHED_DATA_COMPLETE,
182 STATE_TRUNCATE_CACHED_METADATA,
183 STATE_TRUNCATE_CACHED_METADATA_COMPLETE,
184 STATE_PARTIAL_HEADERS_RECEIVED,
185 STATE_CACHE_READ_RESPONSE,
186 STATE_CACHE_READ_RESPONSE_COMPLETE,
187 STATE_CACHE_WRITE_RESPONSE,
188 STATE_CACHE_WRITE_TRUNCATED_RESPONSE,
189 STATE_CACHE_WRITE_RESPONSE_COMPLETE,
190 STATE_CACHE_READ_METADATA,
191 STATE_CACHE_READ_METADATA_COMPLETE,
192 STATE_CACHE_QUERY_DATA,
193 STATE_CACHE_QUERY_DATA_COMPLETE,
194 STATE_CACHE_READ_DATA,
195 STATE_CACHE_READ_DATA_COMPLETE,
196 STATE_CACHE_WRITE_DATA,
197 STATE_CACHE_WRITE_DATA_COMPLETE
200 // Used for categorizing transactions for reporting in histograms. Patterns
201 // cover relatively common use cases being measured and considered for
202 // optimization. Many use cases that are more complex or uncommon are binned
203 // as PATTERN_NOT_COVERED, and details are not reported.
204 // NOTE: This enumeration is used in histograms, so please do not add entries
205 // in the middle.
206 enum TransactionPattern {
207 PATTERN_UNDEFINED,
208 PATTERN_NOT_COVERED,
209 PATTERN_ENTRY_NOT_CACHED,
210 PATTERN_ENTRY_USED,
211 PATTERN_ENTRY_VALIDATED,
212 PATTERN_ENTRY_UPDATED,
213 PATTERN_ENTRY_CANT_CONDITIONALIZE,
214 PATTERN_MAX,
217 // This is a helper function used to trigger a completion callback. It may
218 // only be called if callback_ is non-null.
219 void DoCallback(int rv);
221 // This will trigger the completion callback if appropriate.
222 int HandleResult(int rv);
224 // Runs the state transition loop.
225 int DoLoop(int result);
227 // Each of these methods corresponds to a State value. If there is an
228 // argument, the value corresponds to the return of the previous state or
229 // corresponding callback.
230 int DoGetBackend();
231 int DoGetBackendComplete(int result);
232 int DoSendRequest();
233 int DoSendRequestComplete(int result);
234 int DoSuccessfulSendRequest();
235 int DoNetworkRead();
236 int DoNetworkReadComplete(int result);
237 int DoInitEntry();
238 int DoOpenEntry();
239 int DoOpenEntryComplete(int result);
240 int DoCreateEntry();
241 int DoCreateEntryComplete(int result);
242 int DoDoomEntry();
243 int DoDoomEntryComplete(int result);
244 int DoAddToEntry();
245 int DoAddToEntryComplete(int result);
246 int DoStartPartialCacheValidation();
247 int DoCompletePartialCacheValidation(int result);
248 int DoUpdateCachedResponse();
249 int DoUpdateCachedResponseComplete(int result);
250 int DoOverwriteCachedResponse();
251 int DoTruncateCachedData();
252 int DoTruncateCachedDataComplete(int result);
253 int DoTruncateCachedMetadata();
254 int DoTruncateCachedMetadataComplete(int result);
255 int DoPartialHeadersReceived();
256 int DoCacheReadResponse();
257 int DoCacheReadResponseComplete(int result);
258 int DoCacheWriteResponse();
259 int DoCacheWriteTruncatedResponse();
260 int DoCacheWriteResponseComplete(int result);
261 int DoCacheReadMetadata();
262 int DoCacheReadMetadataComplete(int result);
263 int DoCacheQueryData();
264 int DoCacheQueryDataComplete(int result);
265 int DoCacheReadData();
266 int DoCacheReadDataComplete(int result);
267 int DoCacheWriteData(int num_bytes);
268 int DoCacheWriteDataComplete(int result);
270 // These functions are involved in a field trial testing storing certificates
271 // in seperate entries from the HttpResponseInfo.
272 void ReadCertChain();
273 void WriteCertChain();
275 // Sets request_ and fields derived from it.
276 void SetRequest(const BoundNetLog& net_log, const HttpRequestInfo* request);
278 // Returns true if the request should be handled exclusively by the network
279 // layer (skipping the cache entirely).
280 bool ShouldPassThrough();
282 // Called to begin reading from the cache. Returns network error code.
283 int BeginCacheRead();
285 // Called to begin validating the cache entry. Returns network error code.
286 int BeginCacheValidation();
288 // Called to begin validating an entry that stores partial content. Returns
289 // a network error code.
290 int BeginPartialCacheValidation();
292 // Validates the entry headers against the requested range and continues with
293 // the validation of the rest of the entry. Returns a network error code.
294 int ValidateEntryHeadersAndContinue();
296 // Called to start requests which were given an "if-modified-since" or
297 // "if-none-match" validation header by the caller (NOT when the request was
298 // conditionalized internally in response to LOAD_VALIDATE_CACHE).
299 // Returns a network error code.
300 int BeginExternallyConditionalizedRequest();
302 // Called to restart a network transaction after an error. Returns network
303 // error code.
304 int RestartNetworkRequest();
306 // Called to restart a network transaction with a client certificate.
307 // Returns network error code.
308 int RestartNetworkRequestWithCertificate(X509Certificate* client_cert);
310 // Called to restart a network transaction with authentication credentials.
311 // Returns network error code.
312 int RestartNetworkRequestWithAuth(const AuthCredentials& credentials);
314 // Called to determine if we need to validate the cache entry before using it.
315 bool RequiresValidation();
317 // Called to make the request conditional (to ask the server if the cached
318 // copy is valid). Returns true if able to make the request conditional.
319 bool ConditionalizeRequest();
321 // Makes sure that a 206 response is expected. Returns true on success.
322 // On success, handling_206_ will be set to true if we are processing a
323 // partial entry.
324 bool ValidatePartialResponse();
326 // Handles a response validation error by bypassing the cache.
327 void IgnoreRangeRequest();
329 // Removes content-length and byte range related info if needed.
330 void FixHeadersForHead();
332 // Changes the response code of a range request to be 416 (Requested range not
333 // satisfiable).
334 void FailRangeRequest();
336 // Setups the transaction for reading from the cache entry.
337 int SetupEntryForRead();
339 // Reads data from the network.
340 int ReadFromNetwork(IOBuffer* data, int data_len);
342 // Reads data from the cache entry.
343 int ReadFromEntry(IOBuffer* data, int data_len);
345 // Called to write data to the cache entry. If the write fails, then the
346 // cache entry is destroyed. Future calls to this function will just do
347 // nothing without side-effect. Returns a network error code.
348 int WriteToEntry(int index, int offset, IOBuffer* data, int data_len,
349 const CompletionCallback& callback);
351 // Called to write response_ to the cache entry. |truncated| indicates if the
352 // entry should be marked as incomplete.
353 int WriteResponseInfoToEntry(bool truncated);
355 // Called to append response data to the cache entry. Returns a network error
356 // code.
357 int AppendResponseDataToEntry(IOBuffer* data, int data_len,
358 const CompletionCallback& callback);
360 // Called when we are done writing to the cache entry.
361 void DoneWritingToEntry(bool success);
363 // Returns an error to signal the caller that the current read failed. The
364 // current operation |result| is also logged. If |restart| is true, the
365 // transaction should be restarted.
366 int OnCacheReadError(int result, bool restart);
368 // Called when the cache lock timeout fires.
369 void OnAddToEntryTimeout(base::TimeTicks start_time);
371 // Deletes the current partial cache entry (sparse), and optionally removes
372 // the control object (partial_).
373 void DoomPartialEntry(bool delete_object);
375 // Performs the needed work after receiving data from the network, when
376 // working with range requests.
377 int DoPartialNetworkReadCompleted(int result);
379 // Performs the needed work after receiving data from the cache, when
380 // working with range requests.
381 int DoPartialCacheReadCompleted(int result);
383 // Restarts this transaction after deleting the cached data. It is meant to
384 // be used when the current request cannot be fulfilled due to conflicts
385 // between the byte range request and the cached entry.
386 int DoRestartPartialRequest();
388 // Resets |network_trans_|, which must be non-NULL. Also updates
389 // |old_network_trans_load_timing_|, which must be NULL when this is called.
390 void ResetNetworkTransaction();
392 // Returns true if we should bother attempting to resume this request if it
393 // is aborted while in progress. If |has_data| is true, the size of the stored
394 // data is considered for the result.
395 bool CanResume(bool has_data);
397 void UpdateTransactionPattern(TransactionPattern new_transaction_pattern);
398 void RecordHistograms();
400 // Called to signal completion of asynchronous IO.
401 void OnIOComplete(int result);
403 State next_state_;
404 const HttpRequestInfo* request_;
405 RequestPriority priority_;
406 BoundNetLog net_log_;
407 scoped_ptr<HttpRequestInfo> custom_request_;
408 HttpRequestHeaders request_headers_copy_;
409 // If extra_headers specified a "if-modified-since" or "if-none-match",
410 // |external_validation_| contains the value of those headers.
411 ValidationHeaders external_validation_;
412 base::WeakPtr<HttpCache> cache_;
413 HttpCache::ActiveEntry* entry_;
414 HttpCache::ActiveEntry* new_entry_;
415 scoped_ptr<HttpTransaction> network_trans_;
416 CompletionCallback callback_; // Consumer's callback.
417 HttpResponseInfo response_;
418 HttpResponseInfo auth_response_;
419 const HttpResponseInfo* new_response_;
420 std::string cache_key_;
421 Mode mode_;
422 State target_state_;
423 bool reading_; // We are already reading. Never reverts to false once set.
424 bool invalid_range_; // We may bypass the cache for this request.
425 bool truncated_; // We don't have all the response data.
426 bool is_sparse_; // The data is stored in sparse byte ranges.
427 bool range_requested_; // The user requested a byte range.
428 bool handling_206_; // We must deal with this 206 response.
429 bool cache_pending_; // We are waiting for the HttpCache.
430 bool done_reading_; // All available data was read.
431 bool vary_mismatch_; // The request doesn't match the stored vary data.
432 bool couldnt_conditionalize_request_;
433 bool bypass_lock_for_test_; // A test is exercising the cache lock.
434 scoped_refptr<IOBuffer> read_buf_;
435 int io_buf_len_;
436 int read_offset_;
437 int effective_load_flags_;
438 int write_len_;
439 scoped_ptr<PartialData> partial_; // We are dealing with range requests.
440 UploadProgress final_upload_progress_;
441 CompletionCallback io_callback_;
443 // Members used to track data for histograms.
444 TransactionPattern transaction_pattern_;
445 base::TimeTicks entry_lock_waiting_since_;
446 base::TimeTicks first_cache_access_since_;
447 base::TimeTicks send_request_since_;
449 int64 total_received_bytes_;
451 // Load timing information for the last network request, if any. Set in the
452 // 304 and 206 response cases, as the network transaction may be destroyed
453 // before the caller requests load timing information.
454 scoped_ptr<LoadTimingInfo> old_network_trans_load_timing_;
456 // The helper object to use to create WebSocketHandshakeStreamBase
457 // objects. Only relevant when establishing a WebSocket connection.
458 // This is passed to the underlying network transaction. It is stored here in
459 // case the transaction does not exist yet.
460 WebSocketHandshakeStreamBase::CreateHelper*
461 websocket_handshake_stream_base_create_helper_;
463 BeforeNetworkStartCallback before_network_start_callback_;
464 BeforeProxyHeadersSentCallback before_proxy_headers_sent_callback_;
466 base::WeakPtrFactory<Transaction> weak_factory_;
468 DISALLOW_COPY_AND_ASSIGN(Transaction);
471 } // namespace net
473 #endif // NET_HTTP_HTTP_CACHE_TRANSACTION_H_