message_serialisation.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: Copyright (c) 2024 Cisco Systems
// SPDX-License-Identifier: BSD-2-Clause
 
#pragma once
 
#include "quicr/containers/stream_buffer.h"
#include "quicr/messages/ctrl_message_types.h"
#include "quicr/messages/object.h"
#include "quicr/track_name.h"
 
#include <map>
#include <string>
#include <vector>
 
namespace quicr::messages {
    Bytes& operator<<(Bytes& buffer, const std::optional<Extensions>& extensions);
 
    Bytes& operator<<(Bytes& buffer, const Extensions& extensions);
 
    BytesSpan operator>>(BytesSpan buffer, Extensions& extensions);
 
    void SerializeExtensions(Bytes& buffer,
                             const std::optional<Extensions>& extensions,
                             const std::optional<Extensions>& immutable_extensions);
 
    template<class StreamBufferType>
    bool ParseExtensions(StreamBufferType& buffer,
                         std::optional<std::size_t>& extension_headers_length,
                         std::optional<Extensions>& extensions,
                         std::optional<Extensions>& immutable_extensions,
                         std::size_t& extension_bytes_remaining,
                         std::optional<std::uint64_t>& current_header,
                         std::uint64_t& prev_extension_type);
 
    enum class DatagramHeaderType : uint8_t
    {
        kNotEndOfGroupNoExtensionsObjectId = 0x00,     
        kNotEndOfGroupWithExtensionsObjectId = 0x01,   
        kEndOfGroupNoExtensionsObjectId = 0x02,        
        kEndOfGroupWithExtensionsObjectId = 0x03,      
        kNotEndOfGroupNoExtensionsNoObjectId = 0x04,   
        kNotEndOfGroupWithExtensionsNoObjectId = 0x05, 
        kEndOfGroupNoExtensionsNoObjectId = 0x06,      
        kEndOfGroupWithExtensionsNoObjectId = 0x07     
    };
 
    enum class DatagramStatusType : uint8_t
    {
        kNoExtensions = 0x20,  
        kWithExtensions = 0x21 
    };
 
    enum class FetchHeaderType : uint8_t
    {
        kFetchHeader = 0x05 
    };
 
    enum class SubgroupIdType : std::uint8_t
    {
        kIsZero = 0b00,             
        kSetFromFirstObject = 0b01, 
        kExplicit = 0b10,           
        kReserved = 0b11            
    };
 
    struct StreamHeaderProperties
    {
        const bool extensions; 
        const SubgroupIdType subgroup_id_mode; 
        const bool end_of_group;               
        const bool default_priority;           
        const bool first_object; 
 
        static constexpr std::uint8_t kExtensionsBit = 0x01;  
        static constexpr std::uint8_t kSubgroupIdMask = 0x06; 
        static constexpr std::uint8_t kEndOfGroupBit = 0x08;  
 
        static constexpr std::uint8_t kTypeBit = 0x10;
        static constexpr std::uint8_t kDefaultPriorityBit = 0x20; 
        static constexpr std::uint8_t kFirstObjectBit = 0x40;     
 
        static constexpr std::uint64_t kAllowedBitsMask =
          kExtensionsBit | kSubgroupIdMask | kEndOfGroupBit | kTypeBit | kDefaultPriorityBit | kFirstObjectBit;
 
        explicit constexpr StreamHeaderProperties(const std::uint64_t type)
          : extensions(type & kExtensionsBit)
          , subgroup_id_mode(static_cast<SubgroupIdType>((type & kSubgroupIdMask) >> 1))
          , end_of_group(type & kEndOfGroupBit)
          , default_priority(type & kDefaultPriorityBit)
          , first_object(type & kFirstObjectBit)
        {
            if (!IsValid(type)) {
                throw ProtocolViolationException("Invalid stream header type");
            }
        }
 
        constexpr StreamHeaderProperties(const bool extensions,
                                         const SubgroupIdType subgroup_id_mode,
                                         const bool end_of_group,
                                         const bool default_priority,
                                         const bool first_object)
          : extensions(extensions)
          , subgroup_id_mode(subgroup_id_mode)
          , end_of_group(end_of_group)
          , default_priority(default_priority)
          , first_object(first_object)
        {
            if (subgroup_id_mode == SubgroupIdType::kReserved) {
                throw ProtocolViolationException("Subgroup ID mode cannot be kReserved");
            }
        }
 
        constexpr std::uint64_t GetType() const
        {
            std::uint64_t type = kTypeBit;
            if (extensions) {
                type |= kExtensionsBit;
            }
            type |= static_cast<std::uint64_t>(subgroup_id_mode) << 1;
            if (end_of_group) {
                type |= kEndOfGroupBit;
            }
            if (default_priority) {
                type |= kDefaultPriorityBit;
            }
            if (first_object) {
                type |= kFirstObjectBit;
            }
            return type;
        }
 
        static constexpr bool IsValid(const std::uint64_t type) noexcept
        {
            return (type & ~kAllowedBitsMask) == 0 && (type & kTypeBit) != 0 &&
                   (type & kSubgroupIdMask) != kSubgroupIdMask;
        }
    };
 
    struct DatagramHeaderProperties
    {
        const bool extensions;       
        const bool end_of_group;     
        const bool zero_object_id;   
        const bool default_priority; 
        const bool status;           
 
        static constexpr std::uint8_t kExtensionsBit = 0x01;      
        static constexpr std::uint8_t kEndOfGroupBit = 0x02;      
        static constexpr std::uint8_t kZeroObjectIdBit = 0x04;    
        static constexpr std::uint8_t kDefaultPriorityBit = 0x08; 
        static constexpr std::uint8_t kStatusBit = 0x20;          
 
        constexpr explicit DatagramHeaderProperties(const std::uint8_t type)
          : extensions(type & kExtensionsBit)
          , end_of_group(type & kEndOfGroupBit)
          , zero_object_id(type & kZeroObjectIdBit)
          , default_priority(type & kDefaultPriorityBit)
          , status(type & kStatusBit)
        {
            if (!IsValid(type)) {
                throw ProtocolViolationException("Invalid Datagram type");
            }
        }
 
        constexpr DatagramHeaderProperties(const bool extensions,
                                           const bool end_of_group,
                                           const bool zero_object_id,
                                           const bool default_priority,
                                           const bool status) noexcept
          : extensions(extensions)
          , end_of_group(end_of_group)
          , zero_object_id(zero_object_id)
          , default_priority(default_priority)
          , status(status)
        {
        }
 
        constexpr std::uint8_t GetType() const noexcept
        {
            std::uint8_t type = 0;
            if (extensions) {
                type |= kExtensionsBit;
            }
            if (end_of_group) {
                type |= kEndOfGroupBit;
            }
            if (zero_object_id) {
                type |= kZeroObjectIdBit;
            }
            if (default_priority) {
                type |= kDefaultPriorityBit;
            }
            if (status) {
                type |= kStatusBit;
            }
            return type;
        }
 
        static constexpr bool IsValid(const std::uint8_t type) noexcept
        {
            if (type & 0xD0) {
                return false;
            }
            if (type & kEndOfGroupBit && type & kStatusBit) {
                return false;
            }
            return true;
        }
    };
 
    enum class StreamMessageType
    {
        kFetchHeader,   
        kSubgroupHeader 
    };
 
    [[maybe_unused]] [[nodiscard]] static StreamMessageType GetStreamMessageType(const std::uint64_t type)
    {
        if (type == static_cast<std::uint64_t>(FetchHeaderType::kFetchHeader)) {
            return StreamMessageType::kFetchHeader;
        }
        if (StreamHeaderProperties::IsValid(type)) {
            return StreamMessageType::kSubgroupHeader;
        }
        throw ProtocolViolationException("Invalid stream header type");
    }
 
    struct FetchHeader
    {
        FetchHeaderType type{ FetchHeaderType::kFetchHeader };
        uint64_t request_id; 
 
        template<class StreamBufferType>
        friend bool operator>>(StreamBufferType& buffer, FetchHeader& msg);
 
      private:
        uint64_t current_pos{ 0 };
        bool parse_completed{ false };
    };
 
    BytesSpan operator>>(BytesSpan buffer, FetchHeader& msg);
 
    Bytes& operator<<(Bytes& buffer, const FetchHeader& msg);
 
    struct FetchSerializationProperties
    {
        enum class EndOfRange
        {
            kNonExistent, 
            kUnknown,     
        };
 
        enum class SubgroupIdMode : std::uint8_t
        {
            kZero = 0x00,     
            kPrior = 0x01,    
            kNext = 0x02,     
            kExplicit = 0x03, 
        };
 
        std::optional<EndOfRange> end_of_range; 
 
        std::optional<SubgroupIdMode> subgroup_id_mode;
        bool object_id_delta_present; 
        bool group_id_delta_present;  
        bool priority_present;        
        bool properties_present;      
        bool datagram;                
 
        static constexpr std::uint8_t kSubgroupMask = 0x03;           
        static constexpr std::uint8_t kObjectIdDeltaBit = 0x04;       
        static constexpr std::uint8_t kGroupIdDeltaBit = 0x08;        
        static constexpr std::uint8_t kPriorityBit = 0x10;            
        static constexpr std::uint8_t kPropertiesBit = 0x20;          
        static constexpr std::uint8_t kDatagramBit = 0x40;            
        static constexpr std::uint64_t kEndOfNonExistentRange = 0x8C; 
        static constexpr std::uint64_t kEndOfUnknownRange = 0x10C;    
 
        explicit FetchSerializationProperties(std::uint64_t value);
 
        FetchSerializationProperties(SubgroupIdMode subgroup_id_mode,
                                     bool object_id_delta_present,
                                     bool group_id_delta_present,
                                     bool priority_present,
                                     bool properties_present,
                                     bool datagram) noexcept;
 
        [[nodiscard]] std::uint64_t GetType() const noexcept;
    };
 
    struct FetchObject
    {
        std::optional<FetchSerializationProperties> properties;
        std::optional<std::uint64_t>
          group_id_delta; 
 
        std::optional<std::uint64_t> subgroup_id;
        std::optional<std::uint64_t>
          object_id_delta; 
 
        std::optional<std::uint8_t> publisher_priority;
        std::optional<Extensions> extensions; 
        std::optional<Extensions>
          immutable_extensions; 
 
        uint64_t payload_len{ 0 };
 
        Bytes payload;
 
        template<class StreamBufferType>
        friend bool operator>>(StreamBufferType& buffer, FetchObject& msg);
 
      private:
        std::optional<std::size_t> extension_headers_length;
        std::size_t extension_bytes_remaining{ 0 };
        std::optional<uint64_t> current_tag{};
        std::uint64_t prev_extension_type{ 0 };
        uint64_t current_pos{ 0 };
        bool parse_completed{ false };
    };
 
    struct ResolvedFetchObject
    {
        ObjectHeaders headers; 
 
        Bytes payload;
    };
 
    class FetchObjectSerializationState
    {
      public:
        explicit FetchObjectSerializationState(GroupOrder group_order) noexcept
          : group_order_(group_order)
        {
        }
 
        FetchObject Encode(const ObjectHeaders& headers, std::uint8_t priority, BytesSpan payload);
 
        std::optional<ResolvedFetchObject> Decode(FetchObject&& object);
 
      private:
        GroupOrder group_order_;
        std::optional<std::uint64_t> prior_group_id_;
        std::optional<std::uint64_t> prior_object_id_;
        std::optional<std::uint64_t> prior_subgroup_id_;
        std::optional<std::uint8_t> prior_priority_;
    };
 
    bool operator>>(Bytes& buffer, FetchObject& msg);
 
    Bytes& operator<<(Bytes& buffer, const FetchObject& msg);
 
    //
    // Data Streams
    //
 
    struct ObjectDatagram
    {
        std::uint64_t track_alias; 
        std::uint64_t group_id;    
 
        std::uint64_t object_id;
        std::optional<std::uint8_t> priority; 
        std::optional<Extensions> extensions; 
        std::optional<Extensions> immutable_extensions; 
 
        uint64_t payload_len{ 0 };
 
        ObjectStatus object_status;
        Bytes payload;              
        bool end_of_group{ false }; 
 
        template<class StreamBufferType>
        friend bool operator>>(StreamBufferType& buffer, ObjectDatagram& msg);
 
        std::uint8_t GetType() const { return GetProperties().GetType(); }
 
        DatagramHeaderProperties GetProperties() const
        {
            return DatagramHeaderProperties(extensions.has_value() || immutable_extensions.has_value(),
                                            end_of_group,
                                            object_id == 0,
                                            !priority.has_value(),
                                            false);
        }
 
      private:
        std::optional<DatagramHeaderProperties> properties;
        std::optional<std::size_t> extension_headers_length;
        std::size_t extension_bytes_left{ 0 };
        std::optional<uint64_t> current_tag{};
        std::uint64_t prev_extension_type{ 0 };
        uint64_t current_pos{ 0 };
        bool parse_completed{ false };
    };
 
    Bytes& operator<<(Bytes& buffer, const ObjectDatagram& msg);
 
    struct ObjectDatagramStatus
    {
        std::uint64_t track_alias; 
        std::uint64_t group_id;    
 
        std::uint64_t object_id;
        std::optional<std::uint8_t>
          publisher_priority;                 
        std::optional<Extensions> extensions; 
        std::optional<Extensions> immutable_extensions; 
        ObjectStatus status;                            
 
        template<class StreamBufferType>
        friend bool operator>>(StreamBufferType& buffer, ObjectDatagramStatus& msg);
 
        std::uint64_t GetType() const
        {
            const auto properties = DatagramHeaderProperties(extensions.has_value() || immutable_extensions.has_value(),
                                                             false,
                                                             object_id == 0,
                                                             !publisher_priority.has_value(),
                                                             true);
            return properties.GetType();
        }
 
      private:
        std::optional<DatagramHeaderProperties> properties;
        std::optional<std::size_t> extension_headers_length;
        std::size_t extension_bytes_left{ 0 };
        std::optional<uint64_t> current_tag{};
        std::uint64_t prev_extension_type{ 0 };
        uint64_t current_pos{ 0 };
        bool parse_completed{ false };
    };
 
    Bytes& operator<<(Bytes& buffer, const ObjectDatagramStatus& msg);
 
    // SubGroups
    struct StreamHeaderSubGroup
    {
        std::optional<StreamHeaderProperties> properties;
        std::uint64_t track_alias; 
        std::uint64_t group_id;    
        std::optional<std::uint64_t>
          subgroup_id; 
 
        std::optional<std::uint8_t> publisher_priority;
 
        template<class StreamBufferType>
        friend bool operator>>(StreamBufferType& buffer, StreamHeaderSubGroup& msg);
 
      private:
        uint64_t current_pos{ 0 };
        bool parse_completed{ false };
    };
 
    bool operator>>(Bytes& buffer, StreamHeaderSubGroup& msg);
 
    Bytes& operator<<(Bytes& buffer, const StreamHeaderSubGroup& msg);
 
    struct StreamSubGroupObject
    {
        std::uint64_t object_delta; 
 
        uint64_t payload_len{ 0 };
 
        ObjectStatus object_status;
        std::optional<Extensions> extensions;           
        std::optional<Extensions> immutable_extensions; 
 
        Bytes payload;
 
        std::optional<StreamHeaderProperties> properties{};
 
        template<class StreamBufferType>
        friend bool operator>>(StreamBufferType& buffer, StreamSubGroupObject& msg);
 
      private:
        std::optional<std::size_t> extension_headers_length;
        std::size_t extension_bytes_left{ 0 };
        std::optional<uint64_t> current_tag{};
        std::uint64_t prev_extension_type{ 0 };
        uint64_t current_pos{ 0 };
        bool parse_completed{ false };
    };
 
    bool operator>>(Bytes& buffer, StreamSubGroupObject& msg);
 
    Bytes& operator<<(Bytes& buffer, const StreamSubGroupObject& msg);
 
} // end of namespace quicr::_messages