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