http_stream.h 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218
  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. #ifndef NET_HTTP_HTTP_STREAM_H_
  11. #define NET_HTTP_HTTP_STREAM_H_
  12. #include <stdint.h>
  13. #include <memory>
  14. #include <set>
  15. #include "base/strings/string_piece.h"
  16. #include "net/base/completion_once_callback.h"
  17. #include "net/base/idempotency.h"
  18. #include "net/base/net_error_details.h"
  19. #include "net/base/net_errors.h"
  20. #include "net/base/net_export.h"
  21. #include "net/base/request_priority.h"
  22. #include "net/http/http_raw_request_headers.h"
  23. namespace net {
  24. struct AlternativeService;
  25. class HttpNetworkSession;
  26. class HttpRequestHeaders;
  27. struct HttpRequestInfo;
  28. class HttpResponseInfo;
  29. class IOBuffer;
  30. class IPEndPoint;
  31. struct LoadTimingInfo;
  32. class NetLogWithSource;
  33. class SSLCertRequestInfo;
  34. class SSLInfo;
  35. class NET_EXPORT_PRIVATE HttpStream {
  36. public:
  37. HttpStream() = default;
  38. HttpStream(const HttpStream&) = delete;
  39. HttpStream& operator=(const HttpStream&) = delete;
  40. virtual ~HttpStream() = default;
  41. // Registers the HTTP request for the stream. Must be called before calling
  42. // InitializeStream(). Separating the registration of the request from the
  43. // initialization of the stream allows the connection callback to run prior
  44. // to stream initialization.
  45. //
  46. // The consumer should ensure that request_info points to a valid non-null
  47. // value till final response headers are received; after that point, the
  48. // HttpStream will not access |*request_info| and it may be deleted.
  49. virtual void RegisterRequest(const HttpRequestInfo* request_info) = 0;
  50. // Initializes the stream. Must be called before calling SendRequest().
  51. // If |can_send_early| is true, this stream may send data early without
  52. // confirming the handshake if this is a resumption of a previously
  53. // established connection. Returns a net error code, possibly ERR_IO_PENDING.
  54. virtual int InitializeStream(bool can_send_early,
  55. RequestPriority priority,
  56. const NetLogWithSource& net_log,
  57. CompletionOnceCallback callback) = 0;
  58. // Writes the headers and uploads body data to the underlying socket.
  59. // ERR_IO_PENDING is returned if the operation could not be completed
  60. // synchronously, in which case the result will be passed to the callback
  61. // when available. Returns OK on success.
  62. //
  63. // Some fields in |response| may be filled by this method, but it will not
  64. // contain complete information until ReadResponseHeaders returns.
  65. //
  66. // |response| must remain valid until all sets of headers has been read, or
  67. // the HttpStream is destroyed. There's typically only one set of
  68. // headers, except in the case of 1xx responses (See ReadResponseHeaders).
  69. virtual int SendRequest(const HttpRequestHeaders& request_headers,
  70. HttpResponseInfo* response,
  71. CompletionOnceCallback callback) = 0;
  72. // Reads from the underlying socket until the next set of response headers
  73. // have been completely received. Normally this is called once per request,
  74. // however it may be called again in the event of a 1xx response to read the
  75. // next set of headers.
  76. //
  77. // ERR_IO_PENDING is returned if the operation could not be completed
  78. // synchronously, in which case the result will be passed to the callback when
  79. // available. Returns OK on success. The response headers are available in
  80. // the HttpResponseInfo passed in the original call to SendRequest.
  81. virtual int ReadResponseHeaders(CompletionOnceCallback callback) = 0;
  82. // Reads response body data, up to |buf_len| bytes. |buf_len| should be a
  83. // reasonable size (<2MB). The number of bytes read is returned, or an
  84. // error is returned upon failure. 0 indicates that the request has been
  85. // fully satisfied and there is no more data to read.
  86. // ERR_CONNECTION_CLOSED is returned when the connection has been closed
  87. // prematurely. ERR_IO_PENDING is returned if the operation could not be
  88. // completed synchronously, in which case the result will be passed to the
  89. // callback when available. If the operation is not completed immediately,
  90. // the socket acquires a reference to the provided buffer until the callback
  91. // is invoked or the socket is destroyed.
  92. virtual int ReadResponseBody(IOBuffer* buf,
  93. int buf_len,
  94. CompletionOnceCallback callback) = 0;
  95. // Closes the stream.
  96. // |not_reusable| indicates if the stream can be used for further requests.
  97. // In the case of HTTP, where we re-use the byte-stream (e.g. the connection)
  98. // this means we need to close the connection; in the case of SPDY, where the
  99. // underlying stream is never reused, it has no effect.
  100. // TODO(mmenke): We should fold the |not_reusable| flag into the stream
  101. // implementation itself so that the caller does not need to
  102. // pass it at all. Ideally we'd be able to remove
  103. // CanReuseConnection() and IsResponseBodyComplete().
  104. // TODO(mmenke): We should try and merge Drain() into this method as well.
  105. virtual void Close(bool not_reusable) = 0;
  106. // Indicates if the response body has been completely read.
  107. virtual bool IsResponseBodyComplete() const = 0;
  108. // A stream exists on top of a connection. If the connection has been used
  109. // to successfully exchange data in the past, error handling for the
  110. // stream is done differently. This method returns true if the underlying
  111. // connection is reused or has been connected and idle for some time.
  112. virtual bool IsConnectionReused() const = 0;
  113. // TODO(mmenke): We should fold this into RenewStreamForAuth(), and make that
  114. // method drain the stream as well, if needed (And return asynchronously).
  115. virtual void SetConnectionReused() = 0;
  116. // Checks whether the underlying connection can be reused. The stream's
  117. // connection can be reused if the response headers allow for it, the socket
  118. // is still connected, and the stream exclusively owns the underlying
  119. // connection. SPDY and QUIC streams don't own their own connections, so
  120. // always return false.
  121. virtual bool CanReuseConnection() const = 0;
  122. // Get the total number of bytes received from network for this stream.
  123. virtual int64_t GetTotalReceivedBytes() const = 0;
  124. // Get the total number of bytes sent over the network for this stream.
  125. virtual int64_t GetTotalSentBytes() const = 0;
  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. // Get the SSLInfo associated with this stream's connection. This should
  137. // only be called for streams over SSL sockets, otherwise the behavior is
  138. // undefined.
  139. virtual void GetSSLInfo(SSLInfo* ssl_info) = 0;
  140. // Returns true and populates |alternative_service| if an alternative service
  141. // was used to for this stream. Otherwise returns false.
  142. virtual bool GetAlternativeService(
  143. AlternativeService* alternative_service) const = 0;
  144. // Get the SSLCertRequestInfo associated with this stream's connection.
  145. // This should only be called for streams over SSL sockets, otherwise the
  146. // behavior is undefined.
  147. virtual void GetSSLCertRequestInfo(SSLCertRequestInfo* cert_request_info) = 0;
  148. // Gets the remote endpoint of the socket that the HTTP stream is using, if
  149. // any. Returns OK and fills in |endpoint| if it is available; returns an
  150. // error and does not modify |endpoint| otherwise.
  151. virtual int GetRemoteEndpoint(IPEndPoint* endpoint) = 0;
  152. // In the case of an HTTP error or redirect, flush the response body (usually
  153. // a simple error or "this page has moved") so that we can re-use the
  154. // underlying connection. This stream is responsible for deleting itself when
  155. // draining is complete.
  156. virtual void Drain(HttpNetworkSession* session) = 0;
  157. // Get the network error details this stream is encountering.
  158. // Fills in |details| if it is available; leaves |details| unchanged if it
  159. // is unavailable.
  160. virtual void PopulateNetErrorDetails(NetErrorDetails* details) = 0;
  161. // Called when the priority of the parent transaction changes.
  162. virtual void SetPriority(RequestPriority priority) = 0;
  163. // Returns a new (not initialized) stream using the same underlying
  164. // connection and invalidates the old stream - no further methods should be
  165. // called on the old stream. The caller should ensure that the response body
  166. // from the previous request is drained before calling this method. If the
  167. // subclass does not support renewing the stream, NULL is returned.
  168. virtual std::unique_ptr<HttpStream> RenewStreamForAuth() = 0;
  169. virtual void SetRequestHeadersCallback(RequestHeadersCallback callback) = 0;
  170. // Set the idempotency of the request. No-op by default.
  171. virtual void SetRequestIdempotency(Idempotency idempotency) {}
  172. // Retrieves any DNS aliases for the remote endpoint. Includes all known
  173. // aliases, e.g. from A, AAAA, or HTTPS, not just from the address used for
  174. // the connection, in no particular order.
  175. virtual const std::set<std::string>& GetDnsAliases() const = 0;
  176. // The value in the ACCEPT_CH frame received during TLS handshake via the
  177. // ALPS extension, or the empty string if the server did not send one. Unlike
  178. // Accept-CH header fields received in HTTP responses, this value is available
  179. // before any requests are made.
  180. virtual base::StringPiece GetAcceptChViaAlps() const = 0;
  181. };
  182. } // namespace net
  183. #endif // NET_HTTP_HTTP_STREAM_H_