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