1 // Copyright 2013 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_WEBSOCKETS_WEBSOCKET_EVENT_INTERFACE_H_ 6 #define NET_WEBSOCKETS_WEBSOCKET_EVENT_INTERFACE_H_ 7 8 #include <stdint.h> 9 10 #include <memory> 11 #include <optional> 12 #include <string> 13 #include <vector> 14 15 #include "base/containers/span.h" 16 #include "base/functional/callback_forward.h" 17 #include "base/memory/scoped_refptr.h" 18 #include "net/base/net_export.h" 19 20 class GURL; 21 22 namespace net { 23 24 class AuthChallengeInfo; 25 class AuthCredentials; 26 class IPEndPoint; 27 class HttpResponseHeaders; 28 class SSLInfo; 29 class URLRequest; 30 struct TransportInfo; 31 struct WebSocketHandshakeRequestInfo; 32 struct WebSocketHandshakeResponseInfo; 33 34 // Interface for events sent from the network layer to the content layer. These 35 // events will generally be sent as-is to the renderer process. 36 class NET_EXPORT WebSocketEventInterface { 37 public: 38 typedef int WebSocketMessageType; 39 40 WebSocketEventInterface(const WebSocketEventInterface&) = delete; 41 WebSocketEventInterface& operator=(const WebSocketEventInterface&) = delete; 42 43 virtual ~WebSocketEventInterface() = default; 44 45 // Called when a URLRequest is created for handshaking. 46 virtual void OnCreateURLRequest(URLRequest* request) = 0; 47 48 // Called when OnConnected is called on the URLRequest for handshaking. 49 virtual void OnURLRequestConnected(URLRequest* request, 50 const TransportInfo& info) = 0; 51 52 // Called in response to an AddChannelRequest. This means that a response has 53 // been received from the remote server. 54 virtual void OnAddChannelResponse( 55 std::unique_ptr<WebSocketHandshakeResponseInfo> response, 56 const std::string& selected_subprotocol, 57 const std::string& extensions) = 0; 58 59 // Called when a data frame has been received from the remote host and needs 60 // to be forwarded to the renderer process. 61 // |payload| stays valid as long as both 62 // - the associated WebSocketChannel is valid. 63 // - no further ReadFrames() is called on the associated WebSocketChannel. 64 virtual void OnDataFrame(bool fin, 65 WebSocketMessageType type, 66 base::span<const char> payload) = 0; 67 68 // Returns true if data pipe is full and waiting the renderer process read 69 // out. The network service should not read more from network until that. 70 virtual bool HasPendingDataFrames() = 0; 71 72 // Called once for each call to SendFrame() once the frame has been passed to 73 // the OS. 74 virtual void OnSendDataFrameDone() = 0; 75 76 // Called when the remote server has Started the WebSocket Closing 77 // Handshake. The client should not attempt to send any more messages after 78 // receiving this message. It will be followed by OnDropChannel() when the 79 // closing handshake is complete. 80 virtual void OnClosingHandshake() = 0; 81 82 // Called when the channel has been dropped, either due to a network close, a 83 // network error, or a protocol error. This may or may not be preceeded by a 84 // call to OnClosingHandshake(). 85 // 86 // Warning: Both the |code| and |reason| are passed through to Javascript, so 87 // callers must take care not to provide details that could be useful to 88 // attackers attempting to use WebSockets to probe networks. 89 // 90 // |was_clean| should be true if the closing handshake completed successfully. 91 // 92 // The channel should not be used again after OnDropChannel() has been 93 // called. 94 // 95 // This function deletes the Channel. 96 virtual void OnDropChannel(bool was_clean, 97 uint16_t code, 98 const std::string& reason) = 0; 99 100 // Called when the browser fails the channel, as specified in the spec. 101 // 102 // The channel should not be used again after OnFailChannel() has been 103 // called. 104 // 105 // |message| is a human readable string describing the failure. (It may be 106 // empty.) |net_error| contains the network error code for the failure, which 107 // may be |OK| if the failure was at a higher level. |response_code| contains 108 // the HTTP status code that caused the failure, or |std::nullopt| if the 109 // attempt didn't get that far. 110 // 111 // This function deletes the Channel. 112 virtual void OnFailChannel(const std::string& message, 113 int net_error, 114 std::optional<int> response_code) = 0; 115 116 // Called when the browser starts the WebSocket Opening Handshake. 117 virtual void OnStartOpeningHandshake( 118 std::unique_ptr<WebSocketHandshakeRequestInfo> request) = 0; 119 120 // Callbacks to be used in response to a call to OnSSLCertificateError. Very 121 // similar to content::SSLErrorHandler::Delegate (which we can't use directly 122 // due to layering constraints). 123 class NET_EXPORT SSLErrorCallbacks { 124 public: 125 virtual ~SSLErrorCallbacks() = default; 126 127 // Cancels the SSL response in response to the error. 128 virtual void CancelSSLRequest(int error, const SSLInfo* ssl_info) = 0; 129 130 // Continue with the SSL connection despite the error. 131 virtual void ContinueSSLRequest() = 0; 132 }; 133 134 // Called on SSL Certificate Error during the SSL handshake. Should result in 135 // a call to either ssl_error_callbacks->ContinueSSLRequest() or 136 // ssl_error_callbacks->CancelSSLRequest(). Normally the implementation of 137 // this method will delegate to content::SSLManager::OnSSLCertificateError to 138 // make the actual decision. The callbacks must not be called after the 139 // WebSocketChannel has been destroyed. 140 virtual void OnSSLCertificateError( 141 std::unique_ptr<SSLErrorCallbacks> ssl_error_callbacks, 142 const GURL& url, 143 int net_error, 144 const SSLInfo& ssl_info, 145 bool fatal) = 0; 146 147 // Called when authentication is required. Returns a net error. The opening 148 // handshake is blocked when this function returns ERR_IO_PENDING. 149 // In that case calling |callback| resumes the handshake. |callback| can be 150 // called during the opening handshake. An implementation can rewrite 151 // |*credentials| (in the sync case) or provide new credentials (in the 152 // async case). 153 // Providing null credentials (nullopt in the sync case and nullptr in the 154 // async case) cancels authentication. Otherwise the new credentials are set 155 // and the opening handshake will be retried with the credentials. 156 virtual int OnAuthRequired( 157 const AuthChallengeInfo& auth_info, 158 scoped_refptr<HttpResponseHeaders> response_headers, 159 const IPEndPoint& socket_address, 160 base::OnceCallback<void(const AuthCredentials*)> callback, 161 std::optional<AuthCredentials>* credentials) = 0; 162 163 protected: 164 WebSocketEventInterface() = default; 165 }; 166 167 } // namespace net 168 169 #endif // NET_WEBSOCKETS_WEBSOCKET_EVENT_INTERFACE_H_ 170