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;
26struct LoadTimingInfo;
27
28// This is the transaction that is returned by the HttpCache transaction
29// factory.
30class HttpCache::Transaction : public HttpTransaction {
31 public:
32  // The transaction has the following modes, which apply to how it may access
33  // its cache entry.
34  //
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.
37  //
38  //  o If the mode of the transaction is only READ, then it may only read from
39  //    the cache entry.
40  //
41  //  o If the mode of the transaction is only WRITE, then it may only write to
42  //    the cache entry.
43  //
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).
47  //
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
59  };
60
61  Transaction(RequestPriority priority,
62              HttpCache* cache);
63  virtual ~Transaction();
64
65  Mode mode() const { return mode_; }
66
67  const std::string& key() const { return cache_key_; }
68
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.
75  //
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.
79  //
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);
87
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();
93
94  HttpCache::ActiveEntry* entry() { return entry_; }
95
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;
101
102  const CompletionCallback& io_callback() { return io_callback_; }
103
104  const BoundNetLog& net_log() const;
105
106  // HttpTransaction methods:
107  virtual int Start(const HttpRequestInfo* request_info,
108                    const CompletionCallback& callback,
109                    const BoundNetLog& net_log) OVERRIDE;
110  virtual int RestartIgnoringLastError(
111      const CompletionCallback& callback) OVERRIDE;
112  virtual int RestartWithCertificate(
113      X509Certificate* client_cert,
114      const CompletionCallback& callback) OVERRIDE;
115  virtual int RestartWithAuth(const AuthCredentials& credentials,
116                              const CompletionCallback& callback) OVERRIDE;
117  virtual bool IsReadyToRestartForAuth() OVERRIDE;
118  virtual int Read(IOBuffer* buf,
119                   int buf_len,
120                   const CompletionCallback& callback) OVERRIDE;
121  virtual void StopCaching() OVERRIDE;
122  virtual bool GetFullRequestHeaders(
123      HttpRequestHeaders* headers) const OVERRIDE;
124  virtual int64 GetTotalReceivedBytes() const OVERRIDE;
125  virtual void DoneReading() OVERRIDE;
126  virtual const HttpResponseInfo* GetResponseInfo() const OVERRIDE;
127  virtual LoadState GetLoadState() const OVERRIDE;
128  virtual UploadProgress GetUploadProgress(void) const OVERRIDE;
129  virtual void SetQuicServerInfo(QuicServerInfo* quic_server_info) OVERRIDE;
130  virtual bool GetLoadTimingInfo(
131      LoadTimingInfo* load_timing_info) const OVERRIDE;
132  virtual void SetPriority(RequestPriority priority) OVERRIDE;
133  virtual void SetWebSocketHandshakeStreamCreateHelper(
134      net::WebSocketHandshakeStreamBase::CreateHelper* create_helper) OVERRIDE;
135  virtual void SetBeforeNetworkStartCallback(
136      const BeforeNetworkStartCallback& callback) OVERRIDE;
137  virtual int ResumeNetworkStart() OVERRIDE;
138
139 private:
140  static const size_t kNumValidationHeaders = 2;
141  // Helper struct to pair a header name with its value, for
142  // headers used to validate cache entries.
143  struct ValidationHeaders {
144    ValidationHeaders() : initialized(false) {}
145
146    std::string values[kNumValidationHeaders];
147    bool initialized;
148  };
149
150  enum State {
151    STATE_NONE,
152    STATE_GET_BACKEND,
153    STATE_GET_BACKEND_COMPLETE,
154    STATE_SEND_REQUEST,
155    STATE_SEND_REQUEST_COMPLETE,
156    STATE_SUCCESSFUL_SEND_REQUEST,
157    STATE_NETWORK_READ,
158    STATE_NETWORK_READ_COMPLETE,
159    STATE_INIT_ENTRY,
160    STATE_OPEN_ENTRY,
161    STATE_OPEN_ENTRY_COMPLETE,
162    STATE_CREATE_ENTRY,
163    STATE_CREATE_ENTRY_COMPLETE,
164    STATE_DOOM_ENTRY,
165    STATE_DOOM_ENTRY_COMPLETE,
166    STATE_ADD_TO_ENTRY,
167    STATE_ADD_TO_ENTRY_COMPLETE,
168    STATE_START_PARTIAL_CACHE_VALIDATION,
169    STATE_COMPLETE_PARTIAL_CACHE_VALIDATION,
170    STATE_UPDATE_CACHED_RESPONSE,
171    STATE_UPDATE_CACHED_RESPONSE_COMPLETE,
172    STATE_OVERWRITE_CACHED_RESPONSE,
173    STATE_TRUNCATE_CACHED_DATA,
174    STATE_TRUNCATE_CACHED_DATA_COMPLETE,
175    STATE_TRUNCATE_CACHED_METADATA,
176    STATE_TRUNCATE_CACHED_METADATA_COMPLETE,
177    STATE_PARTIAL_HEADERS_RECEIVED,
178    STATE_CACHE_READ_RESPONSE,
179    STATE_CACHE_READ_RESPONSE_COMPLETE,
180    STATE_CACHE_WRITE_RESPONSE,
181    STATE_CACHE_WRITE_TRUNCATED_RESPONSE,
182    STATE_CACHE_WRITE_RESPONSE_COMPLETE,
183    STATE_CACHE_READ_METADATA,
184    STATE_CACHE_READ_METADATA_COMPLETE,
185    STATE_CACHE_QUERY_DATA,
186    STATE_CACHE_QUERY_DATA_COMPLETE,
187    STATE_CACHE_READ_DATA,
188    STATE_CACHE_READ_DATA_COMPLETE,
189    STATE_CACHE_WRITE_DATA,
190    STATE_CACHE_WRITE_DATA_COMPLETE
191  };
192
193  // Used for categorizing transactions for reporting in histograms. Patterns
194  // cover relatively common use cases being measured and considered for
195  // optimization. Many use cases that are more complex or uncommon are binned
196  // as PATTERN_NOT_COVERED, and details are not reported.
197  // NOTE: This enumeration is used in histograms, so please do not add entries
198  // in the middle.
199  enum TransactionPattern {
200    PATTERN_UNDEFINED,
201    PATTERN_NOT_COVERED,
202    PATTERN_ENTRY_NOT_CACHED,
203    PATTERN_ENTRY_USED,
204    PATTERN_ENTRY_VALIDATED,
205    PATTERN_ENTRY_UPDATED,
206    PATTERN_ENTRY_CANT_CONDITIONALIZE,
207    PATTERN_MAX,
208  };
209
210  // This is a helper function used to trigger a completion callback.  It may
211  // only be called if callback_ is non-null.
212  void DoCallback(int rv);
213
214  // This will trigger the completion callback if appropriate.
215  int HandleResult(int rv);
216
217  // Runs the state transition loop.
218  int DoLoop(int result);
219
220  // Each of these methods corresponds to a State value.  If there is an
221  // argument, the value corresponds to the return of the previous state or
222  // corresponding callback.
223  int DoGetBackend();
224  int DoGetBackendComplete(int result);
225  int DoSendRequest();
226  int DoSendRequestComplete(int result);
227  int DoSuccessfulSendRequest();
228  int DoNetworkRead();
229  int DoNetworkReadComplete(int result);
230  int DoInitEntry();
231  int DoOpenEntry();
232  int DoOpenEntryComplete(int result);
233  int DoCreateEntry();
234  int DoCreateEntryComplete(int result);
235  int DoDoomEntry();
236  int DoDoomEntryComplete(int result);
237  int DoAddToEntry();
238  int DoAddToEntryComplete(int result);
239  int DoStartPartialCacheValidation();
240  int DoCompletePartialCacheValidation(int result);
241  int DoUpdateCachedResponse();
242  int DoUpdateCachedResponseComplete(int result);
243  int DoOverwriteCachedResponse();
244  int DoTruncateCachedData();
245  int DoTruncateCachedDataComplete(int result);
246  int DoTruncateCachedMetadata();
247  int DoTruncateCachedMetadataComplete(int result);
248  int DoPartialHeadersReceived();
249  int DoCacheReadResponse();
250  int DoCacheReadResponseComplete(int result);
251  int DoCacheWriteResponse();
252  int DoCacheWriteTruncatedResponse();
253  int DoCacheWriteResponseComplete(int result);
254  int DoCacheReadMetadata();
255  int DoCacheReadMetadataComplete(int result);
256  int DoCacheQueryData();
257  int DoCacheQueryDataComplete(int result);
258  int DoCacheReadData();
259  int DoCacheReadDataComplete(int result);
260  int DoCacheWriteData(int num_bytes);
261  int DoCacheWriteDataComplete(int result);
262
263  // Sets request_ and fields derived from it.
264  void SetRequest(const BoundNetLog& net_log, const HttpRequestInfo* request);
265
266  // Returns true if the request should be handled exclusively by the network
267  // layer (skipping the cache entirely).
268  bool ShouldPassThrough();
269
270  // Called to begin reading from the cache.  Returns network error code.
271  int BeginCacheRead();
272
273  // Called to begin validating the cache entry.  Returns network error code.
274  int BeginCacheValidation();
275
276  // Called to begin validating an entry that stores partial content.  Returns
277  // a network error code.
278  int BeginPartialCacheValidation();
279
280  // Validates the entry headers against the requested range and continues with
281  // the validation of the rest of the entry.  Returns a network error code.
282  int ValidateEntryHeadersAndContinue();
283
284  // Called to start requests which were given an "if-modified-since" or
285  // "if-none-match" validation header by the caller (NOT when the request was
286  // conditionalized internally in response to LOAD_VALIDATE_CACHE).
287  // Returns a network error code.
288  int BeginExternallyConditionalizedRequest();
289
290  // Called to restart a network transaction after an error.  Returns network
291  // error code.
292  int RestartNetworkRequest();
293
294  // Called to restart a network transaction with a client certificate.
295  // Returns network error code.
296  int RestartNetworkRequestWithCertificate(X509Certificate* client_cert);
297
298  // Called to restart a network transaction with authentication credentials.
299  // Returns network error code.
300  int RestartNetworkRequestWithAuth(const AuthCredentials& credentials);
301
302  // Called to determine if we need to validate the cache entry before using it.
303  bool RequiresValidation();
304
305  // Called to make the request conditional (to ask the server if the cached
306  // copy is valid).  Returns true if able to make the request conditional.
307  bool ConditionalizeRequest();
308
309  // Makes sure that a 206 response is expected.  Returns true on success.
310  // On success, handling_206_ will be set to true if we are processing a
311  // partial entry.
312  bool ValidatePartialResponse();
313
314  // Handles a response validation error by bypassing the cache.
315  void IgnoreRangeRequest();
316
317  // Changes the response code of a range request to be 416 (Requested range not
318  // satisfiable).
319  void FailRangeRequest();
320
321  // Setups the transaction for reading from the cache entry.
322  int SetupEntryForRead();
323
324  // Reads data from the network.
325  int ReadFromNetwork(IOBuffer* data, int data_len);
326
327  // Reads data from the cache entry.
328  int ReadFromEntry(IOBuffer* data, int data_len);
329
330  // Called to write data to the cache entry.  If the write fails, then the
331  // cache entry is destroyed.  Future calls to this function will just do
332  // nothing without side-effect.  Returns a network error code.
333  int WriteToEntry(int index, int offset, IOBuffer* data, int data_len,
334                   const CompletionCallback& callback);
335
336  // Called to write response_ to the cache entry. |truncated| indicates if the
337  // entry should be marked as incomplete.
338  int WriteResponseInfoToEntry(bool truncated);
339
340  // Called to append response data to the cache entry.  Returns a network error
341  // code.
342  int AppendResponseDataToEntry(IOBuffer* data, int data_len,
343                                const CompletionCallback& callback);
344
345  // Called when we are done writing to the cache entry.
346  void DoneWritingToEntry(bool success);
347
348  // Returns an error to signal the caller that the current read failed. The
349  // current operation |result| is also logged. If |restart| is true, the
350  // transaction should be restarted.
351  int OnCacheReadError(int result, bool restart);
352
353  // Deletes the current partial cache entry (sparse), and optionally removes
354  // the control object (partial_).
355  void DoomPartialEntry(bool delete_object);
356
357  // Performs the needed work after receiving data from the network, when
358  // working with range requests.
359  int DoPartialNetworkReadCompleted(int result);
360
361  // Performs the needed work after receiving data from the cache, when
362  // working with range requests.
363  int DoPartialCacheReadCompleted(int result);
364
365  // Restarts this transaction after deleting the cached data. It is meant to
366  // be used when the current request cannot be fulfilled due to conflicts
367  // between the byte range request and the cached entry.
368  int DoRestartPartialRequest();
369
370  // Resets |network_trans_|, which must be non-NULL.  Also updates
371  // |old_network_trans_load_timing_|, which must be NULL when this is called.
372  void ResetNetworkTransaction();
373
374  // Returns true if we should bother attempting to resume this request if it
375  // is aborted while in progress. If |has_data| is true, the size of the stored
376  // data is considered for the result.
377  bool CanResume(bool has_data);
378
379  void UpdateTransactionPattern(TransactionPattern new_transaction_pattern);
380  void RecordHistograms();
381
382  // Called to signal completion of asynchronous IO.
383  void OnIOComplete(int result);
384
385  State next_state_;
386  const HttpRequestInfo* request_;
387  RequestPriority priority_;
388  BoundNetLog net_log_;
389  scoped_ptr<HttpRequestInfo> custom_request_;
390  HttpRequestHeaders request_headers_copy_;
391  // If extra_headers specified a "if-modified-since" or "if-none-match",
392  // |external_validation_| contains the value of those headers.
393  ValidationHeaders external_validation_;
394  base::WeakPtr<HttpCache> cache_;
395  HttpCache::ActiveEntry* entry_;
396  HttpCache::ActiveEntry* new_entry_;
397  scoped_ptr<HttpTransaction> network_trans_;
398  CompletionCallback callback_;  // Consumer's callback.
399  HttpResponseInfo response_;
400  HttpResponseInfo auth_response_;
401  const HttpResponseInfo* new_response_;
402  std::string cache_key_;
403  Mode mode_;
404  State target_state_;
405  bool reading_;  // We are already reading. Never reverts to false once set.
406  bool invalid_range_;  // We may bypass the cache for this request.
407  bool truncated_;  // We don't have all the response data.
408  bool is_sparse_;  // The data is stored in sparse byte ranges.
409  bool range_requested_;  // The user requested a byte range.
410  bool handling_206_;  // We must deal with this 206 response.
411  bool cache_pending_;  // We are waiting for the HttpCache.
412  bool done_reading_;  // All available data was read.
413  bool vary_mismatch_;  // The request doesn't match the stored vary data.
414  bool couldnt_conditionalize_request_;
415  scoped_refptr<IOBuffer> read_buf_;
416  int io_buf_len_;
417  int read_offset_;
418  int effective_load_flags_;
419  int write_len_;
420  scoped_ptr<PartialData> partial_;  // We are dealing with range requests.
421  UploadProgress final_upload_progress_;
422  base::WeakPtrFactory<Transaction> weak_factory_;
423  CompletionCallback io_callback_;
424
425  // Members used to track data for histograms.
426  TransactionPattern transaction_pattern_;
427  base::TimeTicks entry_lock_waiting_since_;
428  base::TimeTicks first_cache_access_since_;
429  base::TimeTicks send_request_since_;
430
431  int64 total_received_bytes_;
432
433  // Load timing information for the last network request, if any.  Set in the
434  // 304 and 206 response cases, as the network transaction may be destroyed
435  // before the caller requests load timing information.
436  scoped_ptr<LoadTimingInfo> old_network_trans_load_timing_;
437
438  // The helper object to use to create WebSocketHandshakeStreamBase
439  // objects. Only relevant when establishing a WebSocket connection.
440  // This is passed to the underlying network transaction. It is stored here in
441  // case the transaction does not exist yet.
442  WebSocketHandshakeStreamBase::CreateHelper*
443      websocket_handshake_stream_base_create_helper_;
444
445  BeforeNetworkStartCallback before_network_start_callback_;
446
447  DISALLOW_COPY_AND_ASSIGN(Transaction);
448};
449
450}  // namespace net
451
452#endif  // NET_HTTP_HTTP_CACHE_TRANSACTION_H_
453