src/net/http/http_cache.h

   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 a HttpTransactionFactory implementation that can be
   6 // layered on top of another HttpTransactionFactory to add HTTP caching.  The
   7 // caching logic follows RFC 2616 (any exceptions are called out in the code).
   8 //
   9 // The HttpCache takes a disk_cache::Backend as a parameter, and uses that for
  10 // the cache storage.
  11 //
  12 // See HttpTransactionFactory and HttpTransaction for more details.
  13
  14 #ifndef NET_HTTP_HTTP_CACHE_H_
  15 #define NET_HTTP_HTTP_CACHE_H_
  16
  17 #include <list>
  18 #include <set>
  19 #include <string>
  20
  21 #include "base/basictypes.h"
  22 #include "base/containers/hash_tables.h"
  23 #include "base/files/file_path.h"
  24 #include "base/memory/scoped_ptr.h"
  25 #include "base/memory/weak_ptr.h"
  26 #include "base/message_loop/message_loop_proxy.h"
  27 #include "base/threading/non_thread_safe.h"
  28 #include "base/time/time.h"
  29 #include "net/base/cache_type.h"
  30 #include "net/base/completion_callback.h"
  31 #include "net/base/load_states.h"
  32 #include "net/base/net_export.h"
  33 #include "net/base/request_priority.h"
  34 #include "net/http/http_network_session.h"
  35 #include "net/http/http_transaction_factory.h"
  36
  37 class GURL;
  38
  39 namespace disk_cache {
  40 class Backend;
  41 class Entry;
  42 }
  43
  44 namespace net {
  45
  46 class CertVerifier;
  47 class HostResolver;
  48 class HttpAuthHandlerFactory;
  49 class HttpNetworkSession;
  50 class HttpResponseInfo;
  51 class HttpServerProperties;
  52 class IOBuffer;
  53 class NetLog;
  54 class NetworkDelegate;
  55 class ServerBoundCertService;
  56 class ProxyService;
  57 class SSLConfigService;
  58 class TransportSecurityState;
  59 class ViewCacheHelper;
  60 struct HttpRequestInfo;
  61
  62 class NET_EXPORT HttpCache : public HttpTransactionFactory,
  63                              public base::SupportsWeakPtr<HttpCache>,
  64                              NON_EXPORTED_BASE(public base::NonThreadSafe) {
  65  public:
  66   // The cache mode of operation.
  67   enum Mode {
  68     // Normal mode just behaves like a standard web cache.
  69     NORMAL = 0,
  70     // Record mode caches everything for purposes of offline playback.
  71     RECORD,
  72     // Playback mode replays from a cache without considering any
  73     // standard invalidations.
  74     PLAYBACK,
  75     // Disables reads and writes from the cache.
  76     // Equivalent to setting LOAD_DISABLE_CACHE on every request.
  77     DISABLE
  78   };
  79
  80   // A BackendFactory creates a backend object to be used by the HttpCache.
  81   class NET_EXPORT BackendFactory {
  82    public:
  83     virtual ~BackendFactory() {}
  84
  85     // The actual method to build the backend. Returns a net error code. If
  86     // ERR_IO_PENDING is returned, the |callback| will be notified when the
  87     // operation completes, and |backend| must remain valid until the
  88     // notification arrives.
  89     // The implementation must not access the factory object after invoking the
  90     // |callback| because the object can be deleted from within the callback.
  91     virtual int CreateBackend(NetLog* net_log,
  92                               scoped_ptr<disk_cache::Backend>* backend,
  93                               const CompletionCallback& callback) = 0;
  94   };
  95
  96   // A default backend factory for the common use cases.
  97   class NET_EXPORT DefaultBackend : public BackendFactory {
  98    public:
  99     // |path| is the destination for any files used by the backend, and
 100     // |cache_thread| is the thread where disk operations should take place. If
 101     // |max_bytes| is  zero, a default value will be calculated automatically.
 102     DefaultBackend(CacheType type, BackendType backend_type,
 103                    const base::FilePath& path, int max_bytes,
 104                    base::MessageLoopProxy* thread);
 105     virtual ~DefaultBackend();
 106
 107     // Returns a factory for an in-memory cache.
 108     static BackendFactory* InMemory(int max_bytes);
 109
 110     // BackendFactory implementation.
 111     virtual int CreateBackend(NetLog* net_log,
 112                               scoped_ptr<disk_cache::Backend>* backend,
 113                               const CompletionCallback& callback) OVERRIDE;
 114
 115    private:
 116     CacheType type_;
 117     BackendType backend_type_;
 118     const base::FilePath path_;
 119     int max_bytes_;
 120     scoped_refptr<base::MessageLoopProxy> thread_;
 121   };
 122
 123   // The disk cache is initialized lazily (by CreateTransaction) in this case.
 124   // The HttpCache takes ownership of the |backend_factory|.
 125   HttpCache(const net::HttpNetworkSession::Params& params,
 126             BackendFactory* backend_factory);
 127
 128   // The disk cache is initialized lazily (by CreateTransaction) in  this case.
 129   // Provide an existing HttpNetworkSession, the cache can construct a
 130   // network layer with a shared HttpNetworkSession in order for multiple
 131   // network layers to share information (e.g. authentication data). The
 132   // HttpCache takes ownership of the |backend_factory|.
 133   HttpCache(HttpNetworkSession* session, BackendFactory* backend_factory);
 134
 135   // Initialize the cache from its component parts, which is useful for
 136   // testing.  The lifetime of the network_layer and backend_factory are managed
 137   // by the HttpCache and will be destroyed using |delete| when the HttpCache is
 138   // destroyed.
 139   HttpCache(HttpTransactionFactory* network_layer,
 140             NetLog* net_log,
 141             BackendFactory* backend_factory);
 142
 143   virtual ~HttpCache();
 144
 145   HttpTransactionFactory* network_layer() { return network_layer_.get(); }
 146
 147   // Retrieves the cache backend for this HttpCache instance. If the backend
 148   // is not initialized yet, this method will initialize it. The return value is
 149   // a network error code, and it could be ERR_IO_PENDING, in which case the
 150   // |callback| will be notified when the operation completes. The pointer that
 151   // receives the |backend| must remain valid until the operation completes.
 152   int GetBackend(disk_cache::Backend** backend,
 153                  const net::CompletionCallback& callback);
 154
 155   // Returns the current backend (can be NULL).
 156   disk_cache::Backend* GetCurrentBackend() const;
 157
 158   // Given a header data blob, convert it to a response info object.
 159   static bool ParseResponseInfo(const char* data, int len,
 160                                 HttpResponseInfo* response_info,
 161                                 bool* response_truncated);
 162
 163   // Writes |buf_len| bytes of metadata stored in |buf| to the cache entry
 164   // referenced by |url|, as long as the entry's |expected_response_time| has
 165   // not changed. This method returns without blocking, and the operation will
 166   // be performed asynchronously without any completion notification.
 167   void WriteMetadata(const GURL& url,
 168                      RequestPriority priority,
 169                      base::Time expected_response_time,
 170                      IOBuffer* buf,
 171                      int buf_len);
 172
 173   // Get/Set the cache's mode.
 174   void set_mode(Mode value) { mode_ = value; }
 175   Mode mode() { return mode_; }
 176
 177   // Close currently active sockets so that fresh page loads will not use any
 178   // recycled connections.  For sockets currently in use, they may not close
 179   // immediately, but they will not be reusable. This is for debugging.
 180   void CloseAllConnections();
 181
 182   // Close all idle connections. Will close all sockets not in active use.
 183   void CloseIdleConnections();
 184
 185   // Called whenever an external cache in the system reuses the resource
 186   // referred to by |url| and |http_method|.
 187   void OnExternalCacheHit(const GURL& url, const std::string& http_method);
 188
 189   // Initializes the Infinite Cache, if selected by the field trial.
 190   void InitializeInfiniteCache(const base::FilePath& path);
 191
 192   // HttpTransactionFactory implementation:
 193   virtual int CreateTransaction(RequestPriority priority,
 194                                 scoped_ptr<HttpTransaction>* trans) OVERRIDE;
 195   virtual HttpCache* GetCache() OVERRIDE;
 196   virtual HttpNetworkSession* GetSession() OVERRIDE;
 197
 198   // Resets the network layer to allow for tests that probe
 199   // network changes (e.g. host unreachable).  The old network layer is
 200   // returned to allow for filter patterns that only intercept
 201   // some creation requests.  Note ownership exchange.
 202   scoped_ptr<HttpTransactionFactory>
 203       SetHttpNetworkTransactionFactoryForTesting(
 204           scoped_ptr<HttpTransactionFactory> new_network_layer);
 205
 206  protected:
 207   // Disk cache entry data indices.
 208   enum {
 209     kResponseInfoIndex = 0,
 210     kResponseContentIndex,
 211     kMetadataIndex,
 212
 213     // Must remain at the end of the enum.
 214     kNumCacheEntryDataIndices
 215   };
 216   friend class ViewCacheHelper;
 217
 218  private:
 219   // Types --------------------------------------------------------------------
 220
 221   class MetadataWriter;
 222   class QuicServerInfoFactoryAdaptor;
 223   class Transaction;
 224   class WorkItem;
 225   friend class Transaction;
 226   struct PendingOp;  // Info for an entry under construction.
 227
 228   typedef std::list<Transaction*> TransactionList;
 229   typedef std::list<WorkItem*> WorkItemList;
 230
 231   struct ActiveEntry {
 232     explicit ActiveEntry(disk_cache::Entry* entry);
 233     ~ActiveEntry();
 234
 235     disk_cache::Entry* disk_entry;
 236     Transaction*       writer;
 237     TransactionList    readers;
 238     TransactionList    pending_queue;
 239     bool               will_process_pending_queue;
 240     bool               doomed;
 241   };
 242
 243   typedef base::hash_map<std::string, ActiveEntry*> ActiveEntriesMap;
 244   typedef base::hash_map<std::string, PendingOp*> PendingOpsMap;
 245   typedef std::set<ActiveEntry*> ActiveEntriesSet;
 246   typedef base::hash_map<std::string, int> PlaybackCacheMap;
 247
 248   // Methods ------------------------------------------------------------------
 249
 250   // Creates the |backend| object and notifies the |callback| when the operation
 251   // completes. Returns an error code.
 252   int CreateBackend(disk_cache::Backend** backend,
 253                     const net::CompletionCallback& callback);
 254
 255   // Makes sure that the backend creation is complete before allowing the
 256   // provided transaction to use the object. Returns an error code.  |trans|
 257   // will be notified via its IO callback if this method returns ERR_IO_PENDING.
 258   // The transaction is free to use the backend directly at any time after
 259   // receiving the notification.
 260   int GetBackendForTransaction(Transaction* trans);
 261
 262   // Generates the cache key for this request.
 263   std::string GenerateCacheKey(const HttpRequestInfo*);
 264
 265   // Dooms the entry selected by |key|, if it is currently in the list of active
 266   // entries.
 267   void DoomActiveEntry(const std::string& key);
 268
 269   // Dooms the entry selected by |key|. |trans| will be notified via its IO
 270   // callback if this method returns ERR_IO_PENDING. The entry can be
 271   // currently in use or not.
 272   int DoomEntry(const std::string& key, Transaction* trans);
 273
 274   // Dooms the entry selected by |key|. |trans| will be notified via its IO
 275   // callback if this method returns ERR_IO_PENDING. The entry should not
 276   // be currently in use.
 277   int AsyncDoomEntry(const std::string& key, Transaction* trans);
 278
 279   // Dooms the entry associated with a GET for a given |url|.
 280   void DoomMainEntryForUrl(const GURL& url);
 281
 282   // Closes a previously doomed entry.
 283   void FinalizeDoomedEntry(ActiveEntry* entry);
 284
 285   // Returns an entry that is currently in use and not doomed, or NULL.
 286   ActiveEntry* FindActiveEntry(const std::string& key);
 287
 288   // Creates a new ActiveEntry and starts tracking it. |disk_entry| is the disk
 289   // cache entry.
 290   ActiveEntry* ActivateEntry(disk_cache::Entry* disk_entry);
 291
 292   // Deletes an ActiveEntry.
 293   void DeactivateEntry(ActiveEntry* entry);
 294
 295   // Deletes an ActiveEntry using an exhaustive search.
 296   void SlowDeactivateEntry(ActiveEntry* entry);
 297
 298   // Returns the PendingOp for the desired |key|. If an entry is not under
 299   // construction already, a new PendingOp structure is created.
 300   PendingOp* GetPendingOp(const std::string& key);
 301
 302   // Deletes a PendingOp.
 303   void DeletePendingOp(PendingOp* pending_op);
 304
 305   // Opens the disk cache entry associated with |key|, returning an ActiveEntry
 306   // in |*entry|. |trans| will be notified via its IO callback if this method
 307   // returns ERR_IO_PENDING.
 308   int OpenEntry(const std::string& key, ActiveEntry** entry,
 309                 Transaction* trans);
 310
 311   // Creates the disk cache entry associated with |key|, returning an
 312   // ActiveEntry in |*entry|. |trans| will be notified via its IO callback if
 313   // this method returns ERR_IO_PENDING.
 314   int CreateEntry(const std::string& key, ActiveEntry** entry,
 315                   Transaction* trans);
 316
 317   // Destroys an ActiveEntry (active or doomed).
 318   void DestroyEntry(ActiveEntry* entry);
 319
 320   // Adds a transaction to an ActiveEntry. If this method returns ERR_IO_PENDING
 321   // the transaction will be notified about completion via its IO callback. This
 322   // method returns ERR_CACHE_RACE to signal the transaction that it cannot be
 323   // added to the provided entry, and it should retry the process with another
 324   // one (in this case, the entry is no longer valid).
 325   int AddTransactionToEntry(ActiveEntry* entry, Transaction* trans);
 326
 327   // Called when the transaction has finished working with this entry. |cancel|
 328   // is true if the operation was cancelled by the caller instead of running
 329   // to completion.
 330   void DoneWithEntry(ActiveEntry* entry, Transaction* trans, bool cancel);
 331
 332   // Called when the transaction has finished writing to this entry. |success|
 333   // is false if the cache entry should be deleted.
 334   void DoneWritingToEntry(ActiveEntry* entry, bool success);
 335
 336   // Called when the transaction has finished reading from this entry.
 337   void DoneReadingFromEntry(ActiveEntry* entry, Transaction* trans);
 338
 339   // Converts the active writer transaction to a reader so that other
 340   // transactions can start reading from this entry.
 341   void ConvertWriterToReader(ActiveEntry* entry);
 342
 343   // Returns the LoadState of the provided pending transaction.
 344   LoadState GetLoadStateForPendingTransaction(const Transaction* trans);
 345
 346   // Removes the transaction |trans|, from the pending list of an entry
 347   // (PendingOp, active or doomed entry).
 348   void RemovePendingTransaction(Transaction* trans);
 349
 350   // Removes the transaction |trans|, from the pending list of |entry|.
 351   bool RemovePendingTransactionFromEntry(ActiveEntry* entry,
 352                                          Transaction* trans);
 353
 354   // Removes the transaction |trans|, from the pending list of |pending_op|.
 355   bool RemovePendingTransactionFromPendingOp(PendingOp* pending_op,
 356                                              Transaction* trans);
 357
 358   // Resumes processing the pending list of |entry|.
 359   void ProcessPendingQueue(ActiveEntry* entry);
 360
 361   // Events (called via PostTask) ---------------------------------------------
 362
 363   void OnProcessPendingQueue(ActiveEntry* entry);
 364
 365   // Callbacks ----------------------------------------------------------------
 366
 367   // Processes BackendCallback notifications.
 368   void OnIOComplete(int result, PendingOp* entry);
 369
 370   // Helper to conditionally delete |pending_op| if the HttpCache object it
 371   // is meant for has been deleted.
 372   //
 373   // TODO(ajwong): The PendingOp lifetime management is very tricky.  It might
 374   // be possible to simplify it using either base::Owned() or base::Passed()
 375   // with the callback.
 376   static void OnPendingOpComplete(const base::WeakPtr<HttpCache>& cache,
 377                                   PendingOp* pending_op,
 378                                   int result);
 379
 380   // Processes the backend creation notification.
 381   void OnBackendCreated(int result, PendingOp* pending_op);
 382
 383   // Variables ----------------------------------------------------------------
 384
 385   NetLog* net_log_;
 386
 387   // Used when lazily constructing the disk_cache_.
 388   scoped_ptr<BackendFactory> backend_factory_;
 389   bool building_backend_;
 390
 391   Mode mode_;
 392
 393   const scoped_ptr<QuicServerInfoFactoryAdaptor> quic_server_info_factory_;
 394
 395   scoped_ptr<HttpTransactionFactory> network_layer_;
 396
 397   scoped_ptr<disk_cache::Backend> disk_cache_;
 398
 399   // The set of active entries indexed by cache key.
 400   ActiveEntriesMap active_entries_;
 401
 402   // The set of doomed entries.
 403   ActiveEntriesSet doomed_entries_;
 404
 405   // The set of entries "under construction".
 406   PendingOpsMap pending_ops_;
 407
 408   scoped_ptr<PlaybackCacheMap> playback_cache_map_;
 409
 410   DISALLOW_COPY_AND_ASSIGN(HttpCache);
 411 };
 412
 413 }  // namespace net
 414
 415 #endif  // NET_HTTP_HTTP_CACHE_H_