chromium/net/third_party/quiche/src/quiche/quic/core/quic_types.h

// Copyright 2014 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.

#ifndef QUICHE_QUIC_CORE_QUIC_TYPES_H_
#define QUICHE_QUIC_CORE_QUIC_TYPES_H_

#include <array>
#include <cstddef>
#include <cstdint>
#include <map>
#include <optional>
#include <ostream>
#include <vector>

#include "absl/container/inlined_vector.h"
#include "absl/strings/str_format.h"
#include "absl/strings/string_view.h"
#include "quiche/quic/core/quic_connection_id.h"
#include "quiche/quic/core/quic_error_codes.h"
#include "quiche/quic/core/quic_packet_number.h"
#include "quiche/quic/core/quic_time.h"
#include "quiche/quic/platform/api/quic_export.h"
#include "quiche/quic/platform/api/quic_flags.h"
#include "quiche/common/quiche_endian.h"
#include "quiche/web_transport/web_transport.h"

namespace quic {

QuicPacketLength;
QuicControlFrameId;
QuicMessageId;

// IMPORTANT: IETF QUIC defines stream IDs and stream counts as being unsigned
// 62-bit numbers. However, we have decided to only support up to 2^32-1 streams
// in order to reduce the size of data structures such as QuicStreamFrame
// and QuicTransmissionInfo, as that allows them to fit in cache lines and has
// visible perfomance impact.
QuicStreamId;

// Count of stream IDs. Used in MAX_STREAMS and STREAMS_BLOCKED frames.
QuicStreamCount;

QuicByteCount;
QuicPacketCount;
QuicPublicResetNonceProof;
QuicStreamOffset;
DiversificationNonce;
PacketTimeVector;

enum : size_t { … };
StatelessResetToken;

// WebTransport session IDs are stream IDs.
WebTransportSessionId;
// WebTransport stream reset codes are 32-bit.
WebTransportStreamError;
// WebTransport session error codes are 32-bit.
WebTransportSessionError;

enum : size_t { … };
QuicPathFrameBuffer;

// The connection id sequence number specifies the order that connection
// ids must be used in. This is also the sequence number carried in
// the IETF QUIC NEW_CONNECTION_ID and RETIRE_CONNECTION_ID frames.
QuicConnectionIdSequenceNumber;

// A custom data that represents application-specific settings.
// In HTTP/3 for example, it includes the encoded SETTINGS.
ApplicationState;

// A struct for functions which consume data payloads and fins.
struct QUICHE_EXPORT QuicConsumedData { … };

// QuicAsyncStatus enumerates the possible results of an asynchronous
// operation.
enum QuicAsyncStatus { … };

// TODO(wtc): see if WriteStatus can be replaced by QuicAsyncStatus.
enum WriteStatus : int16_t { … };

std::string HistogramEnumString(WriteStatus enum_value);
QUICHE_EXPORT std::ostream& operator<<(std::ostream& os,
                                       const WriteStatus& status);

inline std::string HistogramEnumDescription(WriteStatus /*dummy*/) { … }

inline bool IsWriteBlockedStatus(WriteStatus status) { … }

inline bool IsWriteError(WriteStatus status) { … }

// A struct used to return the result of write calls including either the number
// of bytes written or the error code, depending upon the status.
struct QUICHE_EXPORT WriteResult { … };

enum TransmissionType : int8_t { … };

QUICHE_EXPORT std::string TransmissionTypeToString(
    TransmissionType transmission_type);

QUICHE_EXPORT std::ostream& operator<<(std::ostream& os,
                                       TransmissionType transmission_type);

enum HasRetransmittableData : uint8_t { … };

enum IsHandshake : uint8_t { … };

enum class Perspective : uint8_t { … };

QUICHE_EXPORT std::string PerspectiveToString(Perspective perspective);
QUICHE_EXPORT std::ostream& operator<<(std::ostream& os,
                                       const Perspective& perspective);

// Describes whether a ConnectionClose was originated by the peer.
enum class ConnectionCloseSource { … };

QUICHE_EXPORT std::string ConnectionCloseSourceToString(
    ConnectionCloseSource connection_close_source);
QUICHE_EXPORT std::ostream& operator<<(
    std::ostream& os, const ConnectionCloseSource& connection_close_source);

// Should a connection be closed silently or not.
enum class ConnectionCloseBehavior { … };

QUICHE_EXPORT std::string ConnectionCloseBehaviorToString(
    ConnectionCloseBehavior connection_close_behavior);
QUICHE_EXPORT std::ostream& operator<<(
    std::ostream& os, const ConnectionCloseBehavior& connection_close_behavior);

enum QuicFrameType : uint8_t { … };

// Human-readable string suitable for logging.
QUICHE_EXPORT std::string QuicFrameTypeToString(QuicFrameType t);
QUICHE_EXPORT std::ostream& operator<<(std::ostream& os,
                                       const QuicFrameType& t);

// Ietf frame types. These are defined in the IETF QUIC Specification.
// Explicit values are given in the enum so that we can be sure that
// the symbol will map to the correct stream type.
// All types are defined here, even if we have not yet implmented the
// quic/core/stream/.... stuff needed.
// Note: The protocol specifies that frame types are varint-62 encoded,
// further stating that the shortest encoding must be used.  The current set of
// frame types all have values less than 0x40 (64) so can be encoded in a single
// byte, with the two most significant bits being 0. Thus, the following
// enumerations are valid as both the numeric values of frame types AND their
// encodings.
enum QuicIetfFrameType : uint64_t { … };
QUICHE_EXPORT std::ostream& operator<<(std::ostream& os,
                                       const QuicIetfFrameType& c);
QUICHE_EXPORT std::string QuicIetfFrameTypeString(QuicIetfFrameType t);

// Masks for the bits that indicate the frame is a Stream frame vs the
// bits used as flags.
#define IETF_STREAM_FRAME_TYPE_MASK …
#define IETF_STREAM_FRAME_FLAG_MASK …
#define IS_IETF_STREAM_FRAME(_stype_) …

// These are the values encoded in the low-order 3 bits of the
// IETF_STREAMx frame type.
#define IETF_STREAM_FRAME_FIN_BIT …
#define IETF_STREAM_FRAME_LEN_BIT …
#define IETF_STREAM_FRAME_OFF_BIT …

enum QuicPacketNumberLength : uint8_t { … };

// Used to indicate a QuicSequenceNumberLength using two flag bits.
enum QuicPacketNumberLengthFlags { … };

// The public flags are specified in one byte.
enum QuicPacketPublicFlags { … };

// The private flags are specified in one byte.
enum QuicPacketPrivateFlags { … };

// Defines for all types of congestion control algorithms that can be used in
// QUIC. Note that this is separate from the congestion feedback type -
// some congestion control algorithms may use the same feedback type
// (Reno and Cubic are the classic example for that).
enum CongestionControlType { … };

QUICHE_EXPORT std::string CongestionControlTypeToString(
    CongestionControlType cc_type);

// EncryptionLevel enumerates the stages of encryption that a QUIC connection
// progresses through. When retransmitting a packet, the encryption level needs
// to be specified so that it is retransmitted at a level which the peer can
// understand.
enum EncryptionLevel : int8_t { … };

inline bool EncryptionLevelIsValid(EncryptionLevel level) { … }

QUICHE_EXPORT std::string EncryptionLevelToString(EncryptionLevel level);

QUICHE_EXPORT std::ostream& operator<<(std::ostream& os, EncryptionLevel level);

// Enumeration of whether a server endpoint will request a client certificate,
// and whether that endpoint requires a valid client certificate to establish a
// connection.
enum class ClientCertMode : uint8_t { … };

QUICHE_EXPORT absl::string_view ClientCertModeToString(ClientCertMode mode);

QUICHE_EXPORT std::ostream& operator<<(std::ostream& os, ClientCertMode mode);

enum AddressChangeType : uint8_t { … };

QUICHE_EXPORT std::string AddressChangeTypeToString(AddressChangeType type);

QUICHE_EXPORT std::ostream& operator<<(std::ostream& os,
                                       AddressChangeType type);

enum StreamSendingState { … };

enum SentPacketState : uint8_t { … };

enum PacketHeaderFormat : uint8_t { … };

QUICHE_EXPORT std::string PacketHeaderFormatToString(PacketHeaderFormat format);

// Information about a newly acknowledged packet.
struct QUICHE_EXPORT AckedPacket { … };

// A vector of acked packets.
AckedPacketVector;

// Information about a newly lost packet.
struct QUICHE_EXPORT LostPacket { … };

// A vector of lost packets.
LostPacketVector;

// Please note, this value cannot used directly for packet serialization.
enum QuicLongHeaderType : uint8_t { … };

QUICHE_EXPORT std::string QuicLongHeaderTypeToString(QuicLongHeaderType type);

enum QuicPacketHeaderTypeFlags : uint8_t { … };

enum MessageStatus { … };

QUICHE_EXPORT std::string MessageStatusToString(MessageStatus message_status);

// Used to return the result of SendMessage calls
struct QUICHE_EXPORT MessageResult { … };

QUICHE_EXPORT std::string MessageResultToString(MessageResult message_result);

enum WriteStreamDataResult { … };

enum StreamType : uint8_t { … };

// A packet number space is the context in which a packet can be processed and
// acknowledged.
enum PacketNumberSpace : uint8_t { … };

QUICHE_EXPORT std::string PacketNumberSpaceToString(
    PacketNumberSpace packet_number_space);

// Used to return the result of processing a received ACK frame.
enum AckResult { … };

// Used to return the result of processing a received NEW_CID frame.
enum class NewConnectionIdResult : uint8_t { … };

// Indicates the fate of a serialized packet in WritePacket().
enum SerializedPacketFate : uint8_t { … };

QUICHE_EXPORT std::string SerializedPacketFateToString(
    SerializedPacketFate fate);

QUICHE_EXPORT std::ostream& operator<<(std::ostream& os,
                                       const SerializedPacketFate fate);

// There are three different forms of CONNECTION_CLOSE.
enum QuicConnectionCloseType { … };

QUICHE_EXPORT std::ostream& operator<<(std::ostream& os,
                                       const QuicConnectionCloseType type);

QUICHE_EXPORT std::string QuicConnectionCloseTypeString(
    QuicConnectionCloseType type);

// Indicate handshake state of a connection.
enum HandshakeState { … };

struct QUICHE_EXPORT NextReleaseTimeResult { … };

// QuicPacketBuffer bundles a buffer and a function that releases it. Note
// it does not assume ownership of buffer, i.e. it doesn't release the buffer on
// destruction.
struct QUICHE_EXPORT QuicPacketBuffer { … };

// QuicOwnedPacketBuffer is a QuicPacketBuffer that assumes buffer ownership.
struct QUICHE_EXPORT QuicOwnedPacketBuffer : public QuicPacketBuffer { … };

// These values must remain stable as they are uploaded to UMA histograms.
enum class KeyUpdateReason { … };

QUICHE_EXPORT std::ostream& operator<<(std::ostream& os,
                                       const KeyUpdateReason reason);

QUICHE_EXPORT std::string KeyUpdateReasonString(KeyUpdateReason reason);

QuicSignatureAlgorithmVector;

// QuicSSLConfig contains configurations to be applied on a SSL object, which
// overrides the configurations in SSL_CTX.
struct QUICHE_EXPORT QuicSSLConfig { … };

QUICHE_EXPORT bool operator==(const QuicSSLConfig& lhs,
                              const QuicSSLConfig& rhs);

// QuicDelayedSSLConfig contains a subset of SSL config that can be applied
// after BoringSSL's early select certificate callback. This overwrites all SSL
// configs applied before cert selection.
struct QUICHE_EXPORT QuicDelayedSSLConfig { … };

// ParsedClientHello contains client hello information extracted from a fully
// received client hello.
struct QUICHE_EXPORT ParsedClientHello { … };

QUICHE_EXPORT bool operator==(const ParsedClientHello& a,
                              const ParsedClientHello& b);

QUICHE_EXPORT std::ostream& operator<<(std::ostream& os,
                                       const ParsedClientHello& parsed_chlo);

// The two bits in the IP header for Explicit Congestion Notification can take
// one of four values.
enum QuicEcnCodepoint { … };

QUICHE_EXPORT std::string EcnCodepointToString(QuicEcnCodepoint ecn);

// This struct reports the Explicit Congestion Notification (ECN) contents of
// the ACK_ECN frame. They are the cumulative number of QUIC packets received
// for that codepoint in a given Packet Number Space.
struct QUICHE_EXPORT QuicEcnCounts { … };

// Type of the priorities used by a QUIC session.
enum class QuicPriorityType : uint8_t { … };

QUICHE_EXPORT std::string QuicPriorityTypeToString(QuicPriorityType type);
QUICHE_EXPORT std::ostream& operator<<(std::ostream& os, QuicPriorityType type);

}  // namespace quic

#endif  // QUICHE_QUIC_CORE_QUIC_TYPES_H_