web_transport_client.h 5.5 KB

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