1 // Copyright 2021 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_QUIC_WEB_TRANSPORT_CLIENT_H_ 6 #define NET_QUIC_WEB_TRANSPORT_CLIENT_H_ 7 8 #include <optional> 9 #include <string_view> 10 #include <vector> 11 12 #include "base/memory/scoped_refptr.h" 13 #include "net/base/network_anonymization_key.h" 14 #include "net/quic/web_transport_error.h" 15 #include "net/third_party/quiche/src/quiche/quic/core/crypto/web_transport_fingerprint_proof_verifier.h" 16 #include "net/third_party/quiche/src/quiche/quic/core/quic_types.h" 17 #include "net/third_party/quiche/src/quiche/quic/core/web_transport_interface.h" 18 #include "url/gurl.h" 19 #include "url/origin.h" 20 21 namespace net { 22 23 class HttpResponseHeaders; 24 class URLRequestContext; 25 26 // Diagram of allowed state transitions: 27 // 28 // NEW -> CONNECTING -> CONNECTED -> CLOSED 29 // | | 30 // | | 31 // +---> FAILED <---+ 32 // 33 // These values are logged to UMA. Entries should not be renumbered and 34 // numeric values should never be reused. Please keep in sync with 35 // "QuicTransportClientState" in src/tools/metrics/histograms/enums.xml. 36 enum class WebTransportState { 37 // The client object has been created but Connect() has not been called. 38 NEW, 39 // Connection establishment is in progress. No application data can be sent 40 // or received at this point. 41 CONNECTING, 42 // The connection has been established and application data can be sent and 43 // received. 44 CONNECTED, 45 // The connection has been closed gracefully by either endpoint. 46 CLOSED, 47 // The connection has been closed abruptly. 48 FAILED, 49 50 // Total number of possible states. 51 NUM_STATES, 52 }; 53 54 NET_EXPORT std::ostream& operator<<(std::ostream& os, WebTransportState state); 55 // https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/#section-5 56 struct NET_EXPORT WebTransportCloseInfo final { 57 WebTransportCloseInfo(); 58 WebTransportCloseInfo(uint32_t code, std::string_view reason); 59 ~WebTransportCloseInfo(); 60 61 uint32_t code = 0; 62 std::string reason; 63 64 bool operator==(const WebTransportCloseInfo& other) const; 65 }; 66 67 // Returns the string representation of `state`. 68 const char* WebTransportStateString(WebTransportState state); 69 70 // A visitor that gets notified about events that happen to a WebTransport 71 // client. 72 class NET_EXPORT WebTransportClientVisitor { 73 public: 74 virtual ~WebTransportClientVisitor(); 75 76 // State change notifiers. 77 // CONNECTING -> CONNECTED 78 virtual void OnConnected( 79 scoped_refptr<HttpResponseHeaders> response_headers) = 0; 80 // CONNECTING -> FAILED 81 virtual void OnConnectionFailed(const WebTransportError& error) = 0; 82 // CONNECTED -> CLOSED 83 virtual void OnClosed( 84 const std::optional<WebTransportCloseInfo>& close_info) = 0; 85 // CONNECTED -> FAILED 86 virtual void OnError(const WebTransportError& error) = 0; 87 88 virtual void OnIncomingBidirectionalStreamAvailable() = 0; 89 virtual void OnIncomingUnidirectionalStreamAvailable() = 0; 90 virtual void OnDatagramReceived(std::string_view datagram) = 0; 91 virtual void OnCanCreateNewOutgoingBidirectionalStream() = 0; 92 virtual void OnCanCreateNewOutgoingUnidirectionalStream() = 0; 93 virtual void OnDatagramProcessed( 94 std::optional<quic::MessageStatus> status) = 0; 95 }; 96 97 // Parameters that determine the way WebTransport session is established. 98 struct NET_EXPORT WebTransportParameters { 99 WebTransportParameters(); 100 ~WebTransportParameters(); 101 WebTransportParameters(const WebTransportParameters&); 102 WebTransportParameters(WebTransportParameters&&); 103 104 bool allow_pooling = false; 105 106 bool enable_web_transport_http3 = false; 107 108 // A vector of fingerprints for expected server certificates, as described in 109 // https://wicg.github.io/web-transport/#dom-quictransportconfiguration-server_certificate_fingerprints 110 // When empty, Web PKI is used. 111 std::vector<quic::CertificateFingerprint> server_certificate_fingerprints; 112 }; 113 114 // An abstract base for a WebTransport client. Most of the useful operations 115 // are available via the underlying WebTransportSession object, that can be 116 // accessed through the session() method. 117 class NET_EXPORT WebTransportClient { 118 public: 119 virtual ~WebTransportClient() = default; 120 121 // Connect() is an asynchronous operation. Once the operation is finished, 122 // OnConnected() or OnConnectionFailed() is called on the Visitor. 123 virtual void Connect() = 0; 124 125 // Starts the client-initiated termination process. This can be called only 126 // when the state is CONNECTED. The associated visitor is still waiting for 127 // OnClosed or OnError to be called. 128 virtual void Close( 129 const std::optional<WebTransportCloseInfo>& close_info) = 0; 130 131 // session() can be nullptr in states other than CONNECTED. 132 virtual quic::WebTransportSession* session() = 0; 133 }; 134 135 // Creates a WebTransport client for |url| accessed from |origin| with the 136 // provided |anonymization_key|; |visitor| is associated with the resulting 137 // object. This method never returns nullptr; in case of error, the resulting 138 // client will be in the error state. 139 NET_EXPORT 140 std::unique_ptr<WebTransportClient> CreateWebTransportClient( 141 const GURL& url, 142 const url::Origin& origin, 143 WebTransportClientVisitor* visitor, 144 const NetworkAnonymizationKey& anonymization_key, 145 URLRequestContext* context, 146 const WebTransportParameters& parameters); 147 148 } // namespace net 149 150 #endif // NET_QUIC_WEB_TRANSPORT_CLIENT_H_ 151