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