frame_types.h

Go to the documentation of this file.

// BSD 3-Clause License
// Copyright (c) 2024, 🍀☀🌕🌥 🌊
// See the LICENSE file in the project root for full license information.
 
#pragma once
 
#include <array>
#include <cstdint>
#include <optional>
#include <string>
#include <tuple>
#include <variant>
#include <vector>
 
namespace kcenon::network::protocols::quic
{
 
enum class frame_type : uint64_t
{
    padding = 0x00,
    ping = 0x01,
    ack = 0x02,
    ack_ecn = 0x03,
    reset_stream = 0x04,
    stop_sending = 0x05,
    crypto = 0x06,
    new_token = 0x07,
    // STREAM frames: 0x08-0x0f (use stream_base and flags)
    stream_base = 0x08,
    max_data = 0x10,
    max_stream_data = 0x11,
    max_streams_bidi = 0x12,
    max_streams_uni = 0x13,
    data_blocked = 0x14,
    stream_data_blocked = 0x15,
    streams_blocked_bidi = 0x16,
    streams_blocked_uni = 0x17,
    new_connection_id = 0x18,
    retire_connection_id = 0x19,
    path_challenge = 0x1a,
    path_response = 0x1b,
    connection_close = 0x1c,
    connection_close_app = 0x1d,
    handshake_done = 0x1e,
};
 
namespace stream_flags
{
    constexpr uint8_t fin = 0x01;    
    constexpr uint8_t len = 0x02;    
    constexpr uint8_t off = 0x04;    
    constexpr uint8_t mask = 0x07;   
    constexpr uint8_t base = 0x08;   
} // namespace stream_flags
 
[[nodiscard]] constexpr auto is_stream_frame(uint64_t type) noexcept -> bool
{
    return (type >= 0x08 && type <= 0x0f);
}
 
[[nodiscard]] constexpr auto get_stream_flags(uint64_t type) noexcept -> uint8_t
{
    return static_cast<uint8_t>(type & stream_flags::mask);
}
 
[[nodiscard]] constexpr auto make_stream_type(bool has_fin, bool has_length,
                                               bool has_offset) noexcept -> uint8_t
{
    uint8_t type = stream_flags::base;
    if (has_fin) type |= stream_flags::fin;
    if (has_length) type |= stream_flags::len;
    if (has_offset) type |= stream_flags::off;
    return type;
}
 
// ============================================================================
// Frame Structures (RFC 9000 Section 19)
// ============================================================================
 
struct padding_frame
{
    size_t count{1}; 
};
 
struct ping_frame
{
    // PING frames have no content
};
 
struct ack_range
{
    uint64_t gap{0};    
    uint64_t length{0}; 
};
 
struct ecn_counts
{
    uint64_t ect0{0};  
    uint64_t ect1{0};  
    uint64_t ecn_ce{0}; 
};
 
struct ack_frame
{
    uint64_t largest_acknowledged{0}; 
    uint64_t ack_delay{0};            
    std::vector<ack_range> ranges;    
    std::optional<ecn_counts> ecn;    
};
 
struct reset_stream_frame
{
    uint64_t stream_id{0};              
    uint64_t application_error_code{0}; 
    uint64_t final_size{0};             
};
 
struct stop_sending_frame
{
    uint64_t stream_id{0};              
    uint64_t application_error_code{0}; 
};
 
struct crypto_frame
{
    uint64_t offset{0};            
    std::vector<uint8_t> data;     
};
 
struct new_token_frame
{
    std::vector<uint8_t> token; 
};
 
struct stream_frame
{
    uint64_t stream_id{0};         
    uint64_t offset{0};            
    std::vector<uint8_t> data;     
    bool fin{false};               
};
 
struct max_data_frame
{
    uint64_t maximum_data{0}; 
};
 
struct max_stream_data_frame
{
    uint64_t stream_id{0};         
    uint64_t maximum_stream_data{0}; 
};
 
struct max_streams_frame
{
    uint64_t maximum_streams{0}; 
    bool bidirectional{true};    
};
 
struct data_blocked_frame
{
    uint64_t maximum_data{0}; 
};
 
struct stream_data_blocked_frame
{
    uint64_t stream_id{0};         
    uint64_t maximum_stream_data{0}; 
};
 
struct streams_blocked_frame
{
    uint64_t maximum_streams{0}; 
    bool bidirectional{true};    
};
 
struct new_connection_id_frame
{
    uint64_t sequence_number{0};         
    uint64_t retire_prior_to{0};         
    std::vector<uint8_t> connection_id;  
    std::array<uint8_t, 16> stateless_reset_token{}; 
};
 
struct retire_connection_id_frame
{
    uint64_t sequence_number{0}; 
};
 
struct path_challenge_frame
{
    std::array<uint8_t, 8> data{}; 
};
 
struct path_response_frame
{
    std::array<uint8_t, 8> data{}; 
};
 
struct connection_close_frame
{
    uint64_t error_code{0};        
    uint64_t frame_type{0};        
    std::string reason_phrase;     
    bool is_application_error{false}; 
};
 
struct handshake_done_frame
{
    // HANDSHAKE_DONE frames have no content
};
 
// ============================================================================
// Frame Variant
// ============================================================================
 
using frame = std::variant<
    padding_frame,
    ping_frame,
    ack_frame,
    reset_stream_frame,
    stop_sending_frame,
    crypto_frame,
    new_token_frame,
    stream_frame,
    max_data_frame,
    max_stream_data_frame,
    max_streams_frame,
    data_blocked_frame,
    stream_data_blocked_frame,
    streams_blocked_frame,
    new_connection_id_frame,
    retire_connection_id_frame,
    path_challenge_frame,
    path_response_frame,
    connection_close_frame,
    handshake_done_frame
>;
 
[[nodiscard]] auto get_frame_type(const frame& f) -> frame_type;
 
[[nodiscard]] auto frame_type_to_string(frame_type type) -> std::string;
 
} // namespace kcenon::network::protocols::quic