web_transport.h | Explore in Territory

// Copyright (c) 2021 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// This header contains interfaces that abstract away different backing
// protocols for WebTransport.

#ifndef QUICHE_WEB_TRANSPORT_WEB_TRANSPORT_H_
#define QUICHE_WEB_TRANSPORT_WEB_TRANSPORT_H_

#include <cstddef>
#include <cstdint>
#include <memory>
#include <string>

// The dependencies of this API should be kept minimal and independent of
// specific transport implementations.
#include "absl/strings/string_view.h"
#include "absl/time/time.h"
#include "absl/types/span.h"
#include "quiche/common/platform/api/quiche_export.h"
#include "quiche/common/quiche_callbacks.h"
#include "quiche/common/quiche_stream.h"

namespace webtransport {

enum class Perspective { … };

// A numeric ID uniquely identifying a WebTransport stream. Note that by design,
// those IDs are not available in the Web API, and the IDs do not necessarily
// match between client and server perspective, since there may be a proxy
// between them.
StreamId;
// Application-specific error code used for resetting either the read or the
// write half of the stream.
StreamErrorCode;
// Application-specific error code used for closing a WebTransport session.
SessionErrorCode;

// WebTransport priority as defined in
// https://w3c.github.io/webtransport/#webtransportsendstream-write
// The rules are as follows:
// - Streams with the same priority are handled in FIFO order.
// - Streams with the same group_id but different send_order are handled
//   strictly in order.
// - Different group_ids are handled in the FIFO order.
SendGroupId;
SendOrder;
struct QUICHE_EXPORT StreamPriority { … };

// An outcome of a datagram send call.
enum class DatagramStatusCode { … };

// An outcome of a datagram send call, in both enum and human-readable form.
struct QUICHE_EXPORT DatagramStatus { … };

enum class StreamType { … };

// Based on
// https://w3c.github.io/webtransport/#dictdef-webtransportdatagramstats.
struct QUICHE_EXPORT DatagramStats { … };

// Based on https://w3c.github.io/webtransport/#web-transport-stats
// Note that this is currently not a complete implementation of that API, as
// some of those still need to be clarified in
// https://github.com/w3c/webtransport/issues/537
struct QUICHE_EXPORT SessionStats { … };

// The stream visitor is an application-provided object that gets notified about
// events related to a WebTransport stream.  The visitor object is owned by the
// stream itself, meaning that if the stream is ever fully closed, the visitor
// will be garbage-collected.
class QUICHE_EXPORT StreamVisitor : public quiche::ReadStreamVisitor,
                                    public quiche::WriteStreamVisitor { … };

// A stream (either bidirectional or unidirectional) that is contained within a
// WebTransport session.
class QUICHE_EXPORT Stream : public quiche::ReadStream,
                             public quiche::WriteStream,
                             public quiche::TerminableStream { … };

// Visitor that gets notified about events related to a WebTransport session.
class QUICHE_EXPORT SessionVisitor { … };

// An abstract interface for a WebTransport session.
//
// *** AN IMPORTANT NOTE ABOUT STREAM LIFETIMES ***
// Stream objects are managed internally by the underlying QUIC stack, and can
// go away at any time due to the peer resetting the stream. Because of that,
// any pointers to the stream objects returned by this class MUST NEVER be
// retained long-term, except inside the stream visitor (the stream visitor is
// owned by the stream object). If you need to store a reference to a stream,
// consider one of the two following options:
//   (1) store a stream ID,
//   (2) store a weak pointer to the stream visitor, and then access the stream
//       via the said visitor (the visitor is guaranteed to be alive as long as
//       the stream is alive).
class QUICHE_EXPORT Session { … };

}  // namespace webtransport

#endif  // QUICHE_WEB_TRANSPORT_WEB_TRANSPORT_H_
chromium/net/third_party/quiche/src/quiche/web_transport/web_transport.h
