net/http/http_stream.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 // HttpStream provides an abstraction for a basic http streams, SPDY, and QUIC.
   6 // The HttpStream subtype is expected to manage the underlying transport
   7 // appropriately.  For example, a basic http stream will return the transport
   8 // socket to the pool for reuse.  SPDY streams on the other hand leave the
   9 // transport socket management to the SpdySession.
  10
  11 #ifndef NET_HTTP_HTTP_STREAM_H_
  12 #define NET_HTTP_HTTP_STREAM_H_
  13
  14 #include <stdint.h>
  15
  16 #include "base/basictypes.h"
  17 #include "base/memory/scoped_ptr.h"
  18 #include "net/base/completion_callback.h"
  19 #include "net/base/net_export.h"
  20 #include "net/base/request_priority.h"
  21 #include "net/base/upload_progress.h"
  22
  23 namespace net {
  24
  25 class BoundNetLog;
  26 class HttpNetworkSession;
  27 class HttpRequestHeaders;
  28 struct HttpRequestInfo;
  29 class HttpResponseInfo;
  30 class IOBuffer;
  31 struct LoadTimingInfo;
  32 class SSLCertRequestInfo;
  33 class SSLInfo;
  34
  35 class NET_EXPORT_PRIVATE HttpStream {
  36  public:
  37   HttpStream() {}
  38   virtual ~HttpStream() {}
  39
  40   // Initialize stream.  Must be called before calling SendRequest().
  41   // |request_info| must outlive the HttpStream.
  42   // Returns a net error code, possibly ERR_IO_PENDING.
  43   virtual int InitializeStream(const HttpRequestInfo* request_info,
  44                                RequestPriority priority,
  45                                const BoundNetLog& net_log,
  46                                const CompletionCallback& callback) = 0;
  47
  48   // Writes the headers and uploads body data to the underlying socket.
  49   // ERR_IO_PENDING is returned if the operation could not be completed
  50   // synchronously, in which case the result will be passed to the callback
  51   // when available. Returns OK on success.
  52   //
  53   // The callback will only be invoked once the first full set of headers have
  54   // been received, at which point |response| will have been populated with that
  55   // set of headers, and is safe to read, until/unless ReadResponseHeaders is
  56   // called.
  57   //
  58   // |response| must remain valid until all sets of headers has been read, or
  59   // the HttpStream is destroyed. There's typically only one set of
  60   // headers, except in the case of 1xx responses (See ReadResponseHeaders).
  61   virtual int SendRequest(const HttpRequestHeaders& request_headers,
  62                           HttpResponseInfo* response,
  63                           const CompletionCallback& callback) = 0;
  64
  65   // Reads from the underlying socket until the next set of response headers
  66   // have been completely received.  This may only be called on 1xx responses
  67   // after SendRequest has completed successfully, to read the next set of
  68   // headers.
  69   //
  70   // ERR_IO_PENDING is returned if the operation could not be completed
  71   // synchronously, in which case the result will be passed to the callback when
  72   // available. Returns OK on success. The response headers are available in
  73   // the HttpResponseInfo passed in to original call to SendRequest.
  74   virtual int ReadResponseHeaders(const CompletionCallback& callback) = 0;
  75
  76   // Reads response body data, up to |buf_len| bytes. |buf_len| should be a
  77   // reasonable size (<2MB). The number of bytes read is returned, or an
  78   // error is returned upon failure.  0 indicates that the request has been
  79   // fully satisfied and there is no more data to read.
  80   // ERR_CONNECTION_CLOSED is returned when the connection has been closed
  81   // prematurely.  ERR_IO_PENDING is returned if the operation could not be
  82   // completed synchronously, in which case the result will be passed to the
  83   // callback when available. If the operation is not completed immediately,
  84   // the socket acquires a reference to the provided buffer until the callback
  85   // is invoked or the socket is destroyed.
  86   virtual int ReadResponseBody(IOBuffer* buf, int buf_len,
  87                                const CompletionCallback& callback) = 0;
  88
  89   // Closes the stream.
  90   // |not_reusable| indicates if the stream can be used for further requests.
  91   // In the case of HTTP, where we re-use the byte-stream (e.g. the connection)
  92   // this means we need to close the connection; in the case of SPDY, where the
  93   // underlying stream is never reused, it has no effect.
  94   // TODO(mmenke): We should fold the |not_reusable| flag into the stream
  95   //               implementation itself so that the caller does not need to
  96   //               pass it at all.  Ideally we'd be able to remove
  97   //               CanReuseConnection() and IsResponseBodyComplete().
  98   // TODO(mmenke): We should try and merge Drain() into this method as well.
  99   virtual void Close(bool not_reusable) = 0;
 100
 101   // Indicates if the response body has been completely read.
 102   virtual bool IsResponseBodyComplete() const = 0;
 103
 104   // A stream exists on top of a connection.  If the connection has been used
 105   // to successfully exchange data in the past, error handling for the
 106   // stream is done differently.  This method returns true if the underlying
 107   // connection is reused or has been connected and idle for some time.
 108   virtual bool IsConnectionReused() const = 0;
 109   // TODO(mmenke): We should fold this into RenewStreamForAuth(), and make that
 110   //    method drain the stream as well, if needed (And return asynchronously).
 111   virtual void SetConnectionReused() = 0;
 112
 113   // Checks whether the underlying connection can be reused.  The stream's
 114   // connection can be reused if the response headers allow for it, the socket
 115   // is still connected, and the stream exclusively owns the underlying
 116   // connection.  SPDY and QUIC streams don't own their own connections, so
 117   // always return false.
 118   virtual bool CanReuseConnection() const = 0;
 119
 120   // Get the total number of bytes received from network for this stream.
 121   virtual int64 GetTotalReceivedBytes() const = 0;
 122
 123   // Get the total number of bytes sent over the network for this stream.
 124   virtual int64_t GetTotalSentBytes() const = 0;
 125
 126   // Populates the connection establishment part of |load_timing_info|, and
 127   // socket ID.  |load_timing_info| must have all null times when called.
 128   // Returns false and does nothing if there is no underlying connection, either
 129   // because one has yet to be assigned to the stream, or because the underlying
 130   // socket has been closed.
 131   //
 132   // In practice, this means that this function will always succeed any time
 133   // between when the full headers have been received and the stream has been
 134   // closed.
 135   virtual bool GetLoadTimingInfo(LoadTimingInfo* load_timing_info) const = 0;
 136
 137   // Get the SSLInfo associated with this stream's connection.  This should
 138   // only be called for streams over SSL sockets, otherwise the behavior is
 139   // undefined.
 140   virtual void GetSSLInfo(SSLInfo* ssl_info) = 0;
 141
 142   // Get the SSLCertRequestInfo associated with this stream's connection.
 143   // This should only be called for streams over SSL sockets, otherwise the
 144   // behavior is undefined.
 145   virtual void GetSSLCertRequestInfo(SSLCertRequestInfo* cert_request_info) = 0;
 146
 147   // In the case of an HTTP error or redirect, flush the response body (usually
 148   // a simple error or "this page has moved") so that we can re-use the
 149   // underlying connection. This stream is responsible for deleting itself when
 150   // draining is complete.
 151   virtual void Drain(HttpNetworkSession* session) = 0;
 152
 153   // Called when the priority of the parent transaction changes.
 154   virtual void SetPriority(RequestPriority priority) = 0;
 155
 156   // Queries the UploadDataStream for its progress (bytes sent).
 157   virtual UploadProgress GetUploadProgress() const = 0;
 158
 159   // Returns a new (not initialized) stream using the same underlying
 160   // connection and invalidates the old stream - no further methods should be
 161   // called on the old stream.  The caller should ensure that the response body
 162   // from the previous request is drained before calling this method.  If the
 163   // subclass does not support renewing the stream, NULL is returned.
 164   virtual HttpStream* RenewStreamForAuth() = 0;
 165
 166  private:
 167   DISALLOW_COPY_AND_ASSIGN(HttpStream);
 168 };
 169
 170 }  // namespace net
 171
 172 #endif  // NET_HTTP_HTTP_STREAM_H_