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 #ifndef NET_SOCKET_CLIENT_SOCKET_HANDLE_H_ 6 #define NET_SOCKET_CLIENT_SOCKET_HANDLE_H_ 7 8 #include <memory> 9 #include <optional> 10 #include <utility> 11 12 #include "base/check.h" 13 #include "base/functional/bind.h" 14 #include "base/memory/raw_ptr.h" 15 #include "base/memory/scoped_refptr.h" 16 #include "base/memory/weak_ptr.h" 17 #include "base/time/time.h" 18 #include "net/base/ip_endpoint.h" 19 #include "net/base/load_states.h" 20 #include "net/base/load_timing_info.h" 21 #include "net/base/net_errors.h" 22 #include "net/base/net_export.h" 23 #include "net/base/request_priority.h" 24 #include "net/dns/public/resolve_error_info.h" 25 #include "net/log/net_log_source.h" 26 #include "net/log/net_log_with_source.h" 27 #include "net/socket/client_socket_pool.h" 28 #include "net/socket/connection_attempts.h" 29 #include "net/socket/stream_socket.h" 30 #include "net/ssl/ssl_cert_request_info.h" 31 32 namespace net { 33 34 class ConnectJob; 35 struct NetworkTrafficAnnotationTag; 36 class SocketTag; 37 38 // A container for a StreamSocket. 39 // 40 // The handle's |group_id| uniquely identifies the origin and type of the 41 // connection. It is used by the ClientSocketPool to group similar connected 42 // client socket objects. 43 // 44 class NET_EXPORT ClientSocketHandle { 45 public: 46 enum SocketReuseType { 47 UNUSED = 0, // unused socket that just finished connecting 48 UNUSED_IDLE, // unused socket that has been idle for awhile 49 REUSED_IDLE, // previously used socket 50 NUM_TYPES, 51 }; 52 53 ClientSocketHandle(); 54 55 ClientSocketHandle(const ClientSocketHandle&) = delete; 56 ClientSocketHandle& operator=(const ClientSocketHandle&) = delete; 57 58 ~ClientSocketHandle(); 59 60 // Initializes a ClientSocketHandle object, which involves talking to the 61 // ClientSocketPool to obtain a connected socket, possibly reusing one. This 62 // method returns either OK or ERR_IO_PENDING. On ERR_IO_PENDING, |priority| 63 // is used to determine the placement in ClientSocketPool's wait list. 64 // If |respect_limits| is DISABLED, will bypass the wait list, but |priority| 65 // must also be HIGHEST, if set. 66 // 67 // If this method succeeds, then the socket member will be set to an existing 68 // connected socket if an existing connected socket was available to reuse, 69 // otherwise it will be set to a new connected socket. Consumers can then 70 // call is_reused() to see if the socket was reused. If not reusing an 71 // existing socket, ClientSocketPool may need to establish a new 72 // connection using |socket_params|. 73 // 74 // This method returns ERR_IO_PENDING if it cannot complete synchronously, in 75 // which case the consumer will be notified of completion via |callback|. 76 // 77 // If the pool was not able to reuse an existing socket, the new socket 78 // may report a recoverable error. In this case, the return value will 79 // indicate an error and the socket member will be set. If it is determined 80 // that the error is not recoverable, the Disconnect method should be used 81 // on the socket, so that it does not get reused. 82 // 83 // A non-recoverable error may set additional state in the ClientSocketHandle 84 // to allow the caller to determine what went wrong. 85 // 86 // Init may be called multiple times. 87 // 88 // Profiling information for the request is saved to |net_log| if non-NULL. 89 int Init( 90 const ClientSocketPool::GroupId& group_id, 91 scoped_refptr<ClientSocketPool::SocketParams> socket_params, 92 const std::optional<NetworkTrafficAnnotationTag>& proxy_annotation_tag, 93 RequestPriority priority, 94 const SocketTag& socket_tag, 95 ClientSocketPool::RespectLimits respect_limits, 96 CompletionOnceCallback callback, 97 const ClientSocketPool::ProxyAuthCallback& proxy_auth_callback, 98 ClientSocketPool* pool, 99 const NetLogWithSource& net_log); 100 101 // Changes the priority of the ClientSocketHandle to the passed value. 102 // This function is a no-op if |priority| is the same as the current 103 // priority, of if Init() has not been called since the last time 104 // the ClientSocketHandle was reset. 105 void SetPriority(RequestPriority priority); 106 107 // An initialized handle can be reset, which causes it to return to the 108 // un-initialized state. This releases the underlying socket, which in the 109 // case of a socket that still has an established connection, indicates that 110 // the socket may be kept alive for use by a subsequent ClientSocketHandle. 111 // 112 // NOTE: To prevent the socket from being kept alive, be sure to call its 113 // Disconnect method. This will result in the ClientSocketPool deleting the 114 // StreamSocket. 115 void Reset(); 116 117 // Like Reset(), but also closes the socket (if there is one) and cancels any 118 // pending attempt to establish a connection, if the connection attempt is 119 // still ongoing. 120 void ResetAndCloseSocket(); 121 122 // Used after Init() is called, but before the ClientSocketPool has 123 // initialized the ClientSocketHandle. 124 LoadState GetLoadState() const; 125 126 bool IsPoolStalled() const; 127 128 // Adds a higher layered pool on top of the socket pool that |socket_| belongs 129 // to. At most one higher layered pool can be added to a 130 // ClientSocketHandle at a time. On destruction or reset, automatically 131 // removes the higher pool if RemoveHigherLayeredPool has not been called. 132 void AddHigherLayeredPool(HigherLayeredPool* higher_pool); 133 134 // Removes a higher layered pool from the socket pool that |socket_| belongs 135 // to. |higher_pool| must have been added by the above function. 136 void RemoveHigherLayeredPool(HigherLayeredPool* higher_pool); 137 138 // Closes idle sockets that are in the same group with |this|. 139 void CloseIdleSocketsInGroup(const char* net_log_reason_utf8); 140 141 // Returns true when Init() has completed successfully. is_initialized()142 bool is_initialized() const { return is_initialized_; } 143 144 // Sets the portion of LoadTimingInfo related to connection establishment, and 145 // the socket id. |is_reused| is needed because the handle may not have full 146 // reuse information. |load_timing_info| must have all default values when 147 // called. Returns false and makes no changes to |load_timing_info| when 148 // |socket_| is NULL. 149 bool GetLoadTimingInfo(bool is_reused, 150 LoadTimingInfo* load_timing_info) const; 151 152 // Used by ClientSocketPool to initialize the ClientSocketHandle. 153 // 154 // SetSocket() may also be used if this handle is used as simply for 155 // socket storage (e.g., http://crbug.com/37810). 156 void SetSocket(std::unique_ptr<StreamSocket> s); 157 158 // Populates several fields of |this| with error-related information from the 159 // provided completed ConnectJob. Should only be called on ConnectJob failure. 160 void SetAdditionalErrorState(ConnectJob* connect_job); 161 set_reuse_type(SocketReuseType reuse_type)162 void set_reuse_type(SocketReuseType reuse_type) { reuse_type_ = reuse_type; } set_idle_time(base::TimeDelta idle_time)163 void set_idle_time(base::TimeDelta idle_time) { idle_time_ = idle_time; } set_group_generation(int64_t group_generation)164 void set_group_generation(int64_t group_generation) { 165 group_generation_ = group_generation; 166 } set_is_ssl_error(bool is_ssl_error)167 void set_is_ssl_error(bool is_ssl_error) { is_ssl_error_ = is_ssl_error; } set_ssl_cert_request_info(scoped_refptr<SSLCertRequestInfo> ssl_cert_request_info)168 void set_ssl_cert_request_info( 169 scoped_refptr<SSLCertRequestInfo> ssl_cert_request_info) { 170 ssl_cert_request_info_ = std::move(ssl_cert_request_info); 171 } set_connection_attempts(const ConnectionAttempts & attempts)172 void set_connection_attempts(const ConnectionAttempts& attempts) { 173 connection_attempts_ = attempts; 174 } resolve_error_info()175 ResolveErrorInfo resolve_error_info() const { return resolve_error_info_; } 176 177 // Only valid if there is no |socket_|. is_ssl_error()178 bool is_ssl_error() const { 179 DCHECK(!socket_); 180 return is_ssl_error_; 181 } 182 183 // On an ERR_SSL_CLIENT_AUTH_CERT_NEEDED error, the |cert_request_info| field 184 // is set. ssl_cert_request_info()185 scoped_refptr<SSLCertRequestInfo> ssl_cert_request_info() const { 186 return ssl_cert_request_info_; 187 } 188 189 // If the connection failed, returns the connection attempts made. connection_attempts()190 const ConnectionAttempts& connection_attempts() { 191 return connection_attempts_; 192 } 193 socket()194 StreamSocket* socket() { return socket_.get(); } 195 196 // SetSocket() must be called with a new socket before this handle 197 // is destroyed if is_initialized() is true. 198 std::unique_ptr<StreamSocket> PassSocket(); 199 200 // These may only be used if is_initialized() is true. group_id()201 const ClientSocketPool::GroupId& group_id() const { return group_id_; } group_generation()202 int64_t group_generation() const { return group_generation_; } is_reused()203 bool is_reused() const { return reuse_type_ == REUSED_IDLE; } idle_time()204 base::TimeDelta idle_time() const { return idle_time_; } reuse_type()205 SocketReuseType reuse_type() const { return reuse_type_; } connect_timing()206 const LoadTimingInfo::ConnectTiming& connect_timing() const { 207 return connect_timing_; 208 } set_connect_timing(const LoadTimingInfo::ConnectTiming & connect_timing)209 void set_connect_timing(const LoadTimingInfo::ConnectTiming& connect_timing) { 210 connect_timing_ = connect_timing; 211 } 212 GetWeakPtr()213 base::WeakPtr<ClientSocketHandle> GetWeakPtr() { 214 return weak_factory_.GetWeakPtr(); 215 } 216 217 private: 218 // Called on asynchronous completion of an Init() request. 219 void OnIOComplete(int result); 220 221 // Called on completion (both asynchronous & synchronous) of an Init() 222 // request. 223 void HandleInitCompletion(int result); 224 225 // Resets the state of the ClientSocketHandle. |cancel| indicates whether or 226 // not to try to cancel the request with the ClientSocketPool. Does not 227 // reset the supplemental error state. |cancel_connect_job| indicates whether 228 // a pending ConnectJob, if there is one in the SocketPool, should be 229 // cancelled in addition to cancelling the request. It may only be true if 230 // |cancel| is also true. 231 void ResetInternal(bool cancel, bool cancel_connect_job); 232 233 // Resets the supplemental error state. 234 void ResetErrorState(); 235 236 bool is_initialized_ = false; 237 raw_ptr<ClientSocketPool> pool_ = nullptr; 238 raw_ptr<HigherLayeredPool> higher_pool_ = nullptr; 239 std::unique_ptr<StreamSocket> socket_; 240 ClientSocketPool::GroupId group_id_; 241 SocketReuseType reuse_type_ = ClientSocketHandle::UNUSED; 242 CompletionOnceCallback callback_; 243 base::TimeDelta idle_time_; 244 // See ClientSocketPool::ReleaseSocket() for an explanation. 245 int64_t group_generation_ = -1; 246 ResolveErrorInfo resolve_error_info_; 247 bool is_ssl_error_ = false; 248 scoped_refptr<SSLCertRequestInfo> ssl_cert_request_info_; 249 std::vector<ConnectionAttempt> connection_attempts_; 250 251 NetLogSource requesting_source_; 252 253 // Timing information is set when a connection is successfully established. 254 LoadTimingInfo::ConnectTiming connect_timing_; 255 256 base::WeakPtrFactory<ClientSocketHandle> weak_factory_{this}; 257 }; 258 259 } // namespace net 260 261 #endif // NET_SOCKET_CLIENT_SOCKET_HANDLE_H_ 262