1 // Copyright 2011 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 #ifndef NET_HTTP_HTTP_TRANSACTION_H_ 6 #define NET_HTTP_HTTP_TRANSACTION_H_ 7 8 #include <stdint.h> 9 10 #include "net/base/completion_once_callback.h" 11 #include "net/base/completion_repeating_callback.h" 12 #include "net/base/load_states.h" 13 #include "net/base/net_error_details.h" 14 #include "net/base/net_export.h" 15 #include "net/base/request_priority.h" 16 #include "net/base/upload_progress.h" 17 #include "net/http/http_raw_request_headers.h" 18 #include "net/http/http_response_headers.h" 19 #include "net/socket/connection_attempts.h" 20 #include "net/websockets/websocket_handshake_stream_base.h" 21 22 namespace net { 23 24 class AuthCredentials; 25 struct HttpRequestInfo; 26 class HttpResponseInfo; 27 class IOBuffer; 28 struct TransportInfo; 29 struct LoadTimingInfo; 30 class NetLogWithSource; 31 class QuicServerInfo; 32 class SSLPrivateKey; 33 class X509Certificate; 34 35 // Represents a single HTTP transaction (i.e., a single request/response pair). 36 // HTTP redirects are not followed and authentication challenges are not 37 // answered. Cookies are assumed to be managed by the caller. 38 class NET_EXPORT_PRIVATE HttpTransaction { 39 public: 40 // If |*defer| is set to true, the transaction will wait until 41 // ResumeNetworkStart is called before establishing a connection. 42 using BeforeNetworkStartCallback = base::OnceCallback<void(bool* defer)>; 43 44 // Called each time a connection is obtained, before any data is sent. 45 // 46 // |info| describes the newly-obtained connection. 47 // 48 // This can be called multiple times for a single transaction, in the case of 49 // retries, auth challenges, and split range requests. 50 // 51 // If this callback returns an error, the transaction fails with that error. 52 // Otherwise the transaction continues unimpeded. 53 // Must not return ERR_IO_PENDING. 54 // 55 // TODO(crbug.com/986744): Fix handling of OnConnected() when proxy 56 // authentication is required. We should notify this callback that a 57 // connection was established, even though the stream might not be ready for 58 // us to send data through it. 59 using ConnectedCallback = 60 base::RepeatingCallback<int(const TransportInfo& info, 61 CompletionOnceCallback callback)>; 62 63 // Stops any pending IO and destroys the transaction object. 64 virtual ~HttpTransaction() = default; 65 66 // Starts the HTTP transaction (i.e., sends the HTTP request). 67 // 68 // TODO(crbug.com/723786) The consumer should ensure that request_info points 69 // to a valid value till final response headers are received; after that 70 // point, the HttpTransaction will not access |*request_info| and it may be 71 // deleted. 72 // 73 // Returns OK if the transaction could be started synchronously, which means 74 // that the request was served from the cache. ERR_IO_PENDING is returned to 75 // indicate that |callback| will be notified once response info is available 76 // or if an IO error occurs. Any other return value indicates that the 77 // transaction could not be started. 78 // 79 // Regardless of the return value, the caller is expected to keep the 80 // request_info object alive until Destroy is called on the transaction. 81 // 82 // NOTE: The transaction is not responsible for deleting the callback object. 83 // 84 // Profiling information for the request is saved to |net_log| if non-NULL. 85 virtual int Start(const HttpRequestInfo* request_info, 86 CompletionOnceCallback callback, 87 const NetLogWithSource& net_log) = 0; 88 89 // Restarts the HTTP transaction, ignoring the last error. This call can 90 // only be made after a call to Start (or RestartIgnoringLastError) failed. 91 // Once Read has been called, this method cannot be called. This method is 92 // used, for example, to continue past various SSL related errors. 93 // 94 // Not all errors can be ignored using this method. See error code 95 // descriptions for details about errors that can be ignored. 96 // 97 // NOTE: The transaction is not responsible for deleting the callback object. 98 // 99 virtual int RestartIgnoringLastError(CompletionOnceCallback callback) = 0; 100 101 // Restarts the HTTP transaction with a client certificate. 102 virtual int RestartWithCertificate( 103 scoped_refptr<X509Certificate> client_cert, 104 scoped_refptr<SSLPrivateKey> client_private_key, 105 CompletionOnceCallback callback) = 0; 106 107 // Restarts the HTTP transaction with authentication credentials. 108 virtual int RestartWithAuth(const AuthCredentials& credentials, 109 CompletionOnceCallback callback) = 0; 110 111 // Returns true if auth is ready to be continued. Callers should check 112 // this value anytime Start() completes: if it is true, the transaction 113 // can be resumed with RestartWithAuth(L"", L"", callback) to resume 114 // the automatic auth exchange. This notification gives the caller a 115 // chance to process the response headers from all of the intermediate 116 // restarts needed for authentication. 117 virtual bool IsReadyToRestartForAuth() = 0; 118 119 // Once response info is available for the transaction, response data may be 120 // read by calling this method. 121 // 122 // Response data is copied into the given buffer and the number of bytes 123 // copied is returned. ERR_IO_PENDING is returned if response data is not yet 124 // available. |callback| is notified when the data copy completes, and it is 125 // passed the number of bytes that were successfully copied. Or, if a read 126 // error occurs, |callback| is notified of the error. Any other negative 127 // return value indicates that the transaction could not be read. 128 // 129 // NOTE: The transaction is not responsible for deleting the callback object. 130 // If the operation is not completed immediately, the transaction must acquire 131 // a reference to the provided buffer. 132 // 133 virtual int Read(IOBuffer* buf, 134 int buf_len, 135 CompletionOnceCallback callback) = 0; 136 137 // Stops further caching of this request by the HTTP cache, if there is any. 138 // Note that this is merely a hint to the transaction which it may choose to 139 // ignore. 140 virtual void StopCaching() = 0; 141 142 // Get the number of bytes received from network. 143 virtual int64_t GetTotalReceivedBytes() const = 0; 144 145 // Get the number of bytes sent over the network. 146 virtual int64_t GetTotalSentBytes() const = 0; 147 148 // Called to tell the transaction that we have successfully reached the end 149 // of the stream. This is equivalent to performing an extra Read() at the end 150 // that should return 0 bytes. This method should not be called if the 151 // transaction is busy processing a previous operation (like a pending Read). 152 // 153 // DoneReading may also be called before the first Read() to notify that the 154 // entire response body is to be ignored (e.g., in a redirect). 155 virtual void DoneReading() = 0; 156 157 // Returns the response info for this transaction. Must not be called until 158 // |Start| completes. 159 virtual const HttpResponseInfo* GetResponseInfo() const = 0; 160 161 // Returns the load state for this transaction. 162 virtual LoadState GetLoadState() const = 0; 163 164 // SetQuicServerInfo sets a object which reads and writes public information 165 // about a QUIC server. 166 virtual void SetQuicServerInfo(QuicServerInfo* quic_server_info) = 0; 167 168 // Populates all of load timing, except for request start times and receive 169 // headers time. 170 // |load_timing_info| must have all null times when called. Returns false and 171 // does not modify |load_timing_info| if there's no timing information to 172 // provide. 173 virtual bool GetLoadTimingInfo(LoadTimingInfo* load_timing_info) const = 0; 174 175 // Gets the remote endpoint of the socket that the transaction's underlying 176 // stream is using or did use, if any. Returns true and fills in |endpoint| 177 // if it is available; returns false and leaves |endpoint| unchanged if it is 178 // unavailable. 179 virtual bool GetRemoteEndpoint(IPEndPoint* endpoint) const = 0; 180 181 // Populates network error details for this transaction. 182 virtual void PopulateNetErrorDetails(NetErrorDetails* details) const = 0; 183 184 // Called when the priority of the parent job changes. 185 virtual void SetPriority(RequestPriority priority) = 0; 186 187 // Set the WebSocketHandshakeStreamBase::CreateHelper to be used for the 188 // request. Only relevant to WebSocket transactions. Must be called before 189 // Start(). Ownership of |create_helper| remains with the caller. 190 virtual void SetWebSocketHandshakeStreamCreateHelper( 191 WebSocketHandshakeStreamBase::CreateHelper* create_helper) = 0; 192 193 // Sets the callback to receive notification just before network use. 194 virtual void SetBeforeNetworkStartCallback( 195 BeforeNetworkStartCallback callback) = 0; 196 197 // Sets the callback to receive a notification upon connection. 198 virtual void SetConnectedCallback(const ConnectedCallback& callback) = 0; 199 200 virtual void SetRequestHeadersCallback(RequestHeadersCallback callback) = 0; 201 virtual void SetEarlyResponseHeadersCallback( 202 ResponseHeadersCallback callback) = 0; 203 virtual void SetResponseHeadersCallback(ResponseHeadersCallback callback) = 0; 204 205 // Resumes the transaction after being deferred. 206 virtual int ResumeNetworkStart() = 0; 207 208 virtual ConnectionAttempts GetConnectionAttempts() const = 0; 209 210 // Configures the transaction to close the network connection, if any, on 211 // destruction. Intended for cases where keeping the socket alive may leak 212 // data. Does not immediately close the socket. If multiple transactions are 213 // using the same socket, only closes it once all transactions have completed. 214 // 215 // Does not close H2/H3 sessions, but does close H1 tunnels on top of H2/H3 216 // sessions. 217 // 218 // Only applies to currently in-use connections. Does nothing after the last 219 // byte of the response body has been read, as the connection is no longer in 220 // use at that point. 221 virtual void CloseConnectionOnDestruction() = 0; 222 }; 223 224 } // namespace net 225 226 #endif // NET_HTTP_HTTP_TRANSACTION_H_ 227