blob: 9f8bb2c701cb29472739d73b76b3e843d61e3a29 [file] [edit]
// Copyright (c) 2023 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.
// Structured data for message types in draft-ietf-moq-transport-02.
#ifndef QUICHE_QUIC_MOQT_MOQT_MESSAGES_H_
#define QUICHE_QUIC_MOQT_MOQT_MESSAGES_H_
#include <cstddef>
#include <cstdint>
#include <initializer_list>
#include <optional>
#include <string>
#include <variant>
#include "quiche/quic/core/quic_time.h"
#include "quiche/quic/core/quic_types.h"
#include "quiche/quic/core/quic_versions.h"
#include "quiche/quic/moqt/moqt_error.h"
#include "quiche/quic/moqt/moqt_key_value_pair.h"
#include "quiche/quic/moqt/moqt_names.h"
#include "quiche/quic/moqt/moqt_object.h"
#include "quiche/quic/moqt/moqt_priority.h"
#include "quiche/quic/moqt/moqt_session_callbacks.h"
#include "quiche/quic/moqt/moqt_types.h"
#include "quiche/common/platform/api/quiche_export.h"
namespace moqt {
inline constexpr quic::ParsedQuicVersionVector GetMoqtSupportedQuicVersions() {
return quic::ParsedQuicVersionVector{quic::ParsedQuicVersion::RFCv1()};
}
// The maximum length of a message, excluding any OBJECT payload. This prevents
// DoS attack via forcing the parser to buffer a large message (OBJECT payloads
// are not buffered by the parser).
inline constexpr size_t kMaxMessageHeaderSize = 16384;
static constexpr size_t kMaxNewSessionUriLength = 8192;
inline constexpr uint64_t kPaddingStreamType = 0x132B3E28;
inline constexpr uint64_t kPaddingDatagramType = 0x132B3E29;
class QUICHE_EXPORT MoqtDataStreamType {
public:
static constexpr uint64_t kFetch = 0x05;
static constexpr uint64_t kSubgroup = 0x10;
static constexpr uint64_t kProperties = 0x01;
static constexpr uint64_t kEndOfGroup = 0x08;
static constexpr uint64_t kDefaultPriority = 0x20;
static constexpr uint64_t kHasFirstObject = 0x40;
// These two cannot simultaneously be true;
static constexpr uint64_t kFirstObjectId = 0x02;
static constexpr uint64_t kSubgroupId = 0x04;
MoqtDataStreamType() : value_(0) {}
// Factory functions.
static std::optional<MoqtDataStreamType> FromValue(uint64_t value) {
MoqtDataStreamType stream_type(value);
if (stream_type.IsFetch()) {
return stream_type;
}
if (!(value & kSubgroup)) {
return std::nullopt;
}
if (value > (kSubgroup | kProperties | kEndOfGroup | kDefaultPriority |
kFirstObjectId | kSubgroupId | kHasFirstObject)) {
// Reserved bits.
return std::nullopt;
}
if ((value & kSubgroupId) && (value & kFirstObjectId)) {
return std::nullopt;
}
return stream_type;
}
static MoqtDataStreamType Fetch() { return MoqtDataStreamType(kFetch); }
static MoqtDataStreamType Subgroup(uint64_t subgroup_id,
uint64_t first_object_id,
bool no_properties, bool default_priority,
bool has_first_object,
bool end_of_group = false) {
uint64_t value = kSubgroup;
if (!no_properties) {
value |= kProperties;
}
if (end_of_group) {
value |= kEndOfGroup;
}
if (default_priority) {
value |= kDefaultPriority;
}
if (has_first_object) {
value |= kHasFirstObject;
}
if (subgroup_id == 0) {
return MoqtDataStreamType(value);
}
if (subgroup_id == first_object_id) {
value |= kFirstObjectId;
} else {
value |= kSubgroupId;
}
return MoqtDataStreamType(value);
}
MoqtDataStreamType(const MoqtDataStreamType& other) = default;
bool IsFetch() const { return value_ == kFetch; }
bool IsSubgroup() const { return value_ & kSubgroup; }
bool IsSubgroupPresent() const {
return IsSubgroup() && (value_ & kSubgroupId);
}
bool SubgroupIsZero() const {
return IsSubgroup() && !(value_ & (kSubgroupId | kFirstObjectId));
}
bool SubgroupIsFirstObjectId() const {
return IsSubgroup() && (value_ & kFirstObjectId);
}
bool ArePropertiesPresent() const {
return IsSubgroup() && (value_ & kProperties);
}
bool EndOfGroupInStream() const {
return IsSubgroup() && (value_ & kEndOfGroup);
}
bool HasDefaultPriority() const {
return IsSubgroup() && (value_ & kDefaultPriority);
}
bool HasFirstObject() const {
return IsSubgroup() && (value_ & kHasFirstObject);
}
uint64_t value() const { return value_; }
MoqtDataStreamType& operator=(const MoqtDataStreamType& other) = default;
bool operator==(const MoqtDataStreamType& other) const = default;
private:
explicit MoqtDataStreamType(uint64_t value) : value_(value) {}
uint64_t value_;
};
class QUICHE_EXPORT MoqtDatagramType {
public:
static constexpr uint64_t kProperties = 0x01;
static constexpr uint64_t kEndOfGroup = 0x02;
static constexpr uint64_t kZeroObjectId = 0x04;
static constexpr uint64_t kDefaultPriority = 0x08;
static constexpr uint64_t kStatus = 0x20;
// The arguments here are properties of the object. The constructor creates
// the appropriate type given those properties and the spec restrictions.
MoqtDatagramType(bool payload, bool properties, bool end_of_group,
bool default_priority, bool zero_object_id)
: value_(0) {
if (properties) {
value_ |= kProperties;
}
if (zero_object_id) {
value_ |= kZeroObjectId;
}
if (default_priority) {
value_ |= kDefaultPriority;
}
if (!payload && !properties) {
value_ |= kStatus;
} else if (end_of_group) {
value_ |= kEndOfGroup;
}
}
static std::optional<MoqtDatagramType> FromValue(uint64_t value) {
if (value > (kProperties | kEndOfGroup | kZeroObjectId | kDefaultPriority |
kStatus)) {
return std::nullopt;
}
if ((value & kStatus) && (value & kEndOfGroup)) {
return std::nullopt;
}
return MoqtDatagramType(value);
}
bool has_status() const { return value_ & kStatus; }
bool has_default_priority() const { return value_ & kDefaultPriority; }
bool has_object_id() const { return !(value_ & kZeroObjectId); }
bool end_of_group() const { return value_ & kEndOfGroup; }
bool has_properties() const { return value_ & kProperties; }
uint64_t value() const { return value_; }
bool operator==(const MoqtDatagramType& other) const = default;
private:
uint64_t value_;
explicit MoqtDatagramType(uint64_t value) : value_(value) {}
};
enum class QUICHE_EXPORT MoqtMessageType : uint64_t {
kRequestUpdate = 0x02,
kSubscribe = 0x03,
kSubscribeOk = 0x04,
kRequestError = 0x05,
kPublishNamespace = 0x06,
kRequestOk = 0x07,
kNamespace = 0x08,
kPublishDone = 0x0b,
kTrackStatus = 0x0d,
kNamespaceDone = 0x0e,
kPublishSkipped = 0x0f,
kGoAway = 0x10,
kFetch = 0x16,
kFetchOk = 0x18,
kPublish = 0x1d,
kPublishStateNotify = 0x22,
kSubscribeNamespace = 0x50,
kSubscribeTracks = 0x51,
kSetup = 0x2f00,
// QUICHE-specific extensions.
// kObjectAck (OACK for short) is a frame used by the receiver indicating that
// it has received and processed the specified object.
kObjectAck = 0x3184,
};
struct SubgroupPriority {
uint8_t publisher_priority = 0xf0;
uint64_t subgroup_id = 0;
auto operator<=>(const SubgroupPriority&) const = default;
};
struct QUICHE_EXPORT MoqtSetup {
SetupOptions options;
};
// These codes do not appear on the wire.
enum class QUICHE_EXPORT MoqtForwardingPreference : uint8_t {
kSubgroup,
kDatagram,
};
MoqtObjectStatus IntegerToObjectStatus(uint64_t integer);
// The data contained in every Object message, although the message type
// implies some of the values.
// On the wire, objects cannot carry status and payload/properties. However, all
// objects can implicity have Normal status and payload/properties. Furthermore,
// when passed in internal APIs, an EndOfGroup status can indicate that a
// datagram, or last object in a stream, was encoded as being the last object in
// its group.
struct QUICHE_EXPORT MoqtObject {
uint64_t track_alias; // For FETCH, this is the subscribe ID.
uint64_t group_id;
uint64_t object_id;
MoqtPriority publisher_priority;
ObjectProperties properties;
MoqtObjectStatus object_status;
std::optional<uint64_t> subgroup_id; // Only for subgroup objects.
std::optional<bool> first_object_in_subgroup; // Only for subgroup objects.
uint64_t payload_length;
};
class QUICHE_EXPORT MoqtFetchSerialization {
public:
static constexpr uint64_t kSubgroupIdMask = 0x03;
static constexpr uint64_t kSubgroupIdZero = 0x00;
static constexpr uint64_t kPriorSubgroupId = 0x01;
static constexpr uint64_t kPriorSubgroupIdPlusOne = 0x02;
static constexpr uint64_t kHasSubgroupId = 0x03;
static constexpr uint64_t kHasObjectId = 0x04;
static constexpr uint64_t kHasGroupId = 0x08;
static constexpr uint64_t kHasPriority = 0x10;
static constexpr uint64_t kHasProperties = 0x20;
static constexpr uint64_t kIsDatagram = 0x40;
static constexpr uint64_t kMaxFetchSerialization =
kIsDatagram | kHasProperties | kHasPriority | kHasGroupId | kHasObjectId |
kSubgroupIdMask;
static constexpr uint64_t kEndOfNonExistentRange = 0x8c;
static constexpr uint64_t kEndOfUnknownRange = 0x10c;
MoqtFetchSerialization() = default;
// Serialization for the first object in a stream.
MoqtFetchSerialization(const MoqtObject& object) {
if (object.object_status == MoqtObjectStatus::kEndOfNonExistentRange) {
value_ |= kEndOfNonExistentRange;
return;
}
if (object.object_status == MoqtObjectStatus::kEndOfUnknownRange) {
value_ |= kEndOfUnknownRange;
return;
}
if (!object.subgroup_id.has_value()) {
value_ |= kIsDatagram;
} else {
if (*object.subgroup_id == 0) {
value_ |= kSubgroupIdZero;
} else {
value_ |= kHasSubgroupId;
}
}
value_ |= (kHasGroupId | kHasObjectId | kHasPriority);
if (!object.properties.empty()) {
value_ |= kHasProperties;
}
}
// Serialization for a subsequent object in a stream.
MoqtFetchSerialization(const MoqtObject& object,
const PublishedObjectMetadata& previous_object) {
if (object.object_status == MoqtObjectStatus::kEndOfNonExistentRange) {
value_ |= kEndOfNonExistentRange;
return;
}
if (object.object_status == MoqtObjectStatus::kEndOfUnknownRange) {
value_ |= kEndOfUnknownRange;
return;
}
uint64_t value = 0;
if (!object.subgroup_id.has_value()) {
value |= kIsDatagram;
} else if (object.subgroup_id == 0) {
value |= kSubgroupIdZero;
} else if (!previous_object.subgroup.has_value()) {
value |= kHasSubgroupId; // Can't use previous value.
} else if (object.subgroup_id == previous_object.subgroup) {
value |= kPriorSubgroupId;
} else if (*object.subgroup_id == *previous_object.subgroup + 1) {
value |= kPriorSubgroupIdPlusOne;
} else {
value |= kHasSubgroupId;
}
if (object.object_id != previous_object.location.object + 1) {
value |= kHasObjectId;
}
if (object.group_id != previous_object.location.group) {
value |= kHasGroupId;
}
if (object.publisher_priority != previous_object.publisher_priority) {
value |= kHasPriority;
}
if (!object.properties.empty()) {
value |= kHasProperties;
}
value_ = value;
}
static std::optional<MoqtFetchSerialization> FromValue(uint64_t value) {
if (value > kMaxFetchSerialization && value != kEndOfUnknownRange &&
value != kEndOfNonExistentRange) {
return std::nullopt;
}
return MoqtFetchSerialization(value);
}
bool has_subgroup_id() const {
return ((value_ & kSubgroupIdMask) == kHasSubgroupId) && !is_datagram();
}
bool zero_subgroup_id() const {
return (value_ & kSubgroupIdMask) == kSubgroupIdZero && !is_datagram();
}
bool prior_subgroup_id() const {
return (value_ & kSubgroupIdMask) == kPriorSubgroupId && !is_datagram();
}
bool prior_subgroup_id_plus_one() const {
return (value_ & kSubgroupIdMask) == kPriorSubgroupIdPlusOne &&
!is_datagram();
}
bool has_object_id() const { return value_ & kHasObjectId; }
bool has_group_id() const { return value_ & kHasGroupId; }
bool has_priority() const { return value_ & kHasPriority; }
bool has_properties() const { return value_ & kHasProperties; }
bool is_datagram() const { return value_ & kIsDatagram; }
bool end_of_non_existent_range() const {
return value_ == kEndOfNonExistentRange;
}
bool end_of_unknown_range() const { return value_ == kEndOfUnknownRange; }
uint64_t value() const { return value_; }
private:
MoqtFetchSerialization(uint64_t value) : value_(value) {}
uint64_t value_ = 0;
};
using MoqtRequestError = MoqtRequestErrorInfo;
struct QUICHE_EXPORT MoqtSubscribe {
uint64_t request_id;
FullTrackName full_track_name;
MessageParameters parameters;
};
struct QUICHE_EXPORT MoqtSubscribeOk {
uint64_t track_alias;
MessageParameters parameters;
TrackProperties properties;
};
struct QUICHE_EXPORT MoqtPublishDone {
PublishDoneCode status_code;
uint64_t stream_count;
std::string error_reason;
};
struct QUICHE_EXPORT MoqtRequestUpdate {
uint64_t request_id;
MessageParameters parameters;
};
struct QUICHE_EXPORT MoqtPublishNamespace {
uint64_t request_id;
TrackNamespace track_namespace;
MessageParameters parameters;
};
using MoqtRequestOk = TrackStatusOkData;
struct QUICHE_EXPORT MoqtTrackStatus {
uint64_t request_id;
FullTrackName full_track_name;
MessageParameters parameters;
};
struct QUICHE_EXPORT MoqtGoAway {
std::string new_session_uri;
quic::QuicTimeDelta timeout = quic::QuicTimeDelta::Zero();
};
struct QUICHE_EXPORT MoqtSubscribeNamespace {
uint64_t request_id;
TrackNamespace track_namespace_prefix;
MessageParameters parameters;
};
struct QUICHE_EXPORT MoqtSubscribeTracks {
uint64_t request_id;
TrackNamespace track_namespace_prefix;
MessageParameters parameters;
};
struct QUICHE_EXPORT MoqtNamespace {
TrackNamespace track_namespace_suffix;
};
struct QUICHE_EXPORT MoqtNamespaceDone {
TrackNamespace track_namespace_suffix;
};
struct QUICHE_EXPORT MoqtPublishSkipped {
FullTrackName name;
};
enum class QUICHE_EXPORT FetchType : uint64_t {
kStandalone = 0x1,
kRelativeJoining = 0x2,
kAbsoluteJoining = 0x3,
};
struct StandaloneFetch {
FullTrackName full_track_name;
Location start_location;
Location end_location;
bool operator==(const StandaloneFetch& other) const = default;
bool operator!=(const StandaloneFetch& other) const = default;
};
struct JoiningFetchRelative {
JoiningFetchRelative(uint64_t joining_request_id, uint64_t joining_start)
: joining_request_id(joining_request_id), joining_start(joining_start) {}
uint64_t joining_request_id;
uint64_t joining_start;
bool operator==(const JoiningFetchRelative& other) const {
return joining_request_id == other.joining_request_id &&
joining_start == other.joining_start;
}
bool operator!=(const JoiningFetchRelative& other) const {
return !(*this == other);
}
};
struct JoiningFetchAbsolute {
JoiningFetchAbsolute(uint64_t joining_request_id, uint64_t joining_start)
: joining_request_id(joining_request_id), joining_start(joining_start) {}
uint64_t joining_request_id;
uint64_t joining_start;
bool operator==(const JoiningFetchAbsolute& other) const {
return joining_request_id == other.joining_request_id &&
joining_start == other.joining_start;
}
bool operator!=(const JoiningFetchAbsolute& other) const {
return !(*this == other);
}
};
struct QUICHE_EXPORT MoqtFetch {
uint64_t request_id;
std::variant<StandaloneFetch, JoiningFetchRelative, JoiningFetchAbsolute>
fetch;
MessageParameters parameters;
};
using MoqtFetchOk = FetchOkData;
struct QUICHE_EXPORT MoqtPublish {
uint64_t request_id;
FullTrackName full_track_name;
uint64_t track_alias;
MessageParameters parameters;
TrackProperties properties;
};
struct QUICHE_EXPORT MoqtPublishStateNotify {
MessageParameters parameters;
};
// All of the three values in this message are encoded as varints.
// `delta_from_deadline` is encoded as an absolute value, with the lowest bit
// indicating the sign (0 if positive).
struct QUICHE_EXPORT MoqtObjectAck {
uint64_t group_id;
uint64_t object_id;
// Positive if the object has been received before the deadline.
quic::QuicTimeDelta delta_from_deadline = quic::QuicTimeDelta::Zero();
};
// Returns false if the parameters cannot be in |message type|.
MoqtError SetupOptionsAllowedByMessage(const SetupOptions& options,
quic::Perspective sender_perspective,
bool webtrans);
// Returns false if |parameters| cannot be in |message_type|. Will trigger
// QUICHE_BUG if |message_type| is REQUEST_OK, REQUEST_UPDATE, or a message
// without parameters. Called by MoqtParser.
bool ParametersAllowedByMessage(const MessageParameters& parameters,
MoqtMessageType message_type);
// Will remove from |parameters| any parameters that are not allowed in
// |message_type|. Will trigger QUICHE_BUG if |message_type| is REQUEST_OK,
// REQUEST_UPDATE, or a message without parameters. Called by MoqtParser.
void SanitizeParameters(MessageParameters& parameters,
MoqtMessageType message_type);
// Returns false if |parameters| cannot be in a REQUEST_UPDATE for
// |updated_type|. Called by the bidi stream visitor. If |updated_type| is
// REQUEST_OK, that corresponds to PUBLISH_OK (as other OK messages cannot be
// updated).
bool ParametersAllowedByRequestUpdate(const MessageParameters& parameters,
MoqtMessageType updated_type);
// Will remove from |parameters| any parameters that are not allowed in a
// REQUEST_UPDATE for |updated_type|. Will trigger QUICHE_BUG if |updated_type|
// is REQUEST_OK or a message without parameters. Called by the bidi stream
// visitor. If |updated_type| is REQUEST_OK, that corresponds to PUBLISH_OK (as
// other OK messages cannot be updated).
void SanitizeUpdateParameters(MessageParameters& parameters,
MoqtMessageType updated_type);
// Returns false if |parameters| cannot be in a REQUEST_OK in response to
// |request_type|. Called by the bidi stream visitor. SUBSCRIBE_OK and FETCH_OK
// are distinct message types to be handled by ParametersAllowedByMessage().
bool ParametersAllowedByRequestOk(const MessageParameters& parameters,
MoqtMessageType type_of_ok);
// Will remove from |parameters| any parameters that are not allowed in a
// REQUEST_OK in response to |type_of_ok|. Called by the bidi stream visitor.
// SUBSCRIBE_OK and FETCH_OK are distinct message types to be handled by
// SanitizeParameters().
void SanitizeRequestOkParameters(MessageParameters& parameters,
MoqtMessageType type_of_ok);
// Returns false if |redirect| cannot be in a REQUEST_ERROR in response to
// |request_type|. Called by the bidi stream visitor.
bool RedirectAllowedByRequestError(const std::optional<Redirect>& redirect,
MoqtMessageType request_type);
std::string MoqtMessageTypeToString(MoqtMessageType message_type);
std::string MoqtDataStreamTypeToString(MoqtDataStreamType type);
std::string MoqtFetchSerializationToString(MoqtFetchSerialization type);
std::string MoqtDatagramTypeToString(MoqtDatagramType type);
std::string MoqtForwardingPreferenceToString(
MoqtForwardingPreference preference);
} // namespace moqt
#endif // QUICHE_QUIC_MOQT_MOQT_MESSAGES_H_