QUIC variable-length integer encoding/decoding (RFC 9000 Section 16) More...

#include <varint.h>

Collaboration diagram for kcenon::network::protocols::quic::varint:

Static Public Member Functions
static auto	encode (uint64_t value) -> std::vector< uint8_t >
	Encode a value to variable-length format.

static auto	encode_with_length (uint64_t value, size_t min_length) -> Result< std::vector< uint8_t > >
	Encode with minimum length requirement.

static auto	decode (std::span< const uint8_t > data) -> Result< std::pair< uint64_t, size_t > >
	Decode variable-length integer from buffer.

static constexpr auto	encoded_length (uint64_t value) noexcept -> size_t
	Get the number of bytes needed to encode a value.

static constexpr auto	length_from_prefix (uint8_t first_byte) noexcept -> size_t
	Get encoded length from the first byte's prefix.

static constexpr auto	is_valid (uint64_t value) noexcept -> bool
	Check if a value can be encoded as a varint.

Static Public Attributes
static constexpr uint64_t	max_1byte = 63
	Maximum value for each encoded length.

static constexpr uint64_t	max_2byte = 16383

static constexpr uint64_t	max_4byte = 1073741823

static constexpr uint64_t	max_8byte = varint_max

Static Private Attributes
static constexpr uint8_t	prefix_1byte = 0x00

static constexpr uint8_t	prefix_2byte = 0x40

static constexpr uint8_t	prefix_4byte = 0x80

static constexpr uint8_t	prefix_8byte = 0xC0

static constexpr uint8_t	prefix_mask = 0xC0

static constexpr uint8_t	value_mask = 0x3F

Detailed Description

QUIC variable-length integer encoding/decoding (RFC 9000 Section 16)

QUIC uses a variable-length integer encoding with 2-bit length prefix:

2-Bit Value	Length	Usable Bits	Range
0b00	1 byte	6	0-63
0b01	2 bytes	14	0-16383
0b10	4 bytes	30	0-1073741823
0b11	8 bytes	62	0-4611686018427387903

The two most significant bits of the first byte indicate the length.

Definition at line 38 of file varint.h.

Member Function Documentation

◆ decode()

auto kcenon::network::protocols::quic::varint::decode ( std::span< const uint8_t > data ) -> Result<std::pair<uint64_t, size_t>>

staticnodiscard

Decode variable-length integer from buffer.

Parameters

data	Input buffer

Returns: Result containing (decoded_value, bytes_consumed) or error

Definition at line 146 of file varint.cpp.

{
    if (data.empty())
    {
        return error<std::pair<uint64_t, size_t>>(
            error_codes::common_errors::invalid_argument,
            "Empty buffer",
            "quic::varint",
            "Cannot decode from empty buffer"
        );
    }
 
    const uint8_t first_byte = data[0];
    const size_t length = length_from_prefix(first_byte);
 
    if (data.size() < length)
    {
        return error<std::pair<uint64_t, size_t>>(
            error_codes::common_errors::invalid_argument,
            "Insufficient data",
            "quic::varint",
            "Buffer too small for encoded length"
        );
    }
 
    uint64_t value = first_byte & value_mask;
 
    for (size_t i = 1; i < length; ++i)
    {
        value = (value << 8) | data[i];
    }
 
    return ok(std::make_pair(value, length));
}

References kcenon::network::protocols::quic::error, kcenon::network::error_codes::common_errors::invalid_argument, and kcenon::network::ok().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ encode()

auto kcenon::network::protocols::quic::varint::encode ( uint64_t value ) -> std::vector<uint8_t>

staticnodiscard

Encode a value to variable-length format.

Parameters

value Value to encode (must be <= varint_max)

Returns: Encoded byte vector

Note: Values exceeding varint_max will be clamped

Definition at line 10 of file varint.cpp.

{
    if (value <= max_1byte)
    {
        // 6-bit: prefix 0b00
        return {static_cast<uint8_t>(value)};
    }
 
    if (value <= max_2byte)
    {
        // 14-bit: prefix 0b01
        return {
            static_cast<uint8_t>(prefix_2byte | ((value >> 8) & value_mask)),
            static_cast<uint8_t>(value & 0xFF)
        };
    }
 
    if (value <= max_4byte)
    {
        // 30-bit: prefix 0b10
        return {
            static_cast<uint8_t>(prefix_4byte | ((value >> 24) & value_mask)),
            static_cast<uint8_t>((value >> 16) & 0xFF),
            static_cast<uint8_t>((value >> 8) & 0xFF),
            static_cast<uint8_t>(value & 0xFF)
        };
    }
 
    // 62-bit: prefix 0b11
    // Clamp to max if exceeding varint_max
    if (value > varint_max)
    {
        value = varint_max;
    }
 
    return {
        static_cast<uint8_t>(prefix_8byte | ((value >> 56) & value_mask)),
        static_cast<uint8_t>((value >> 48) & 0xFF),
        static_cast<uint8_t>((value >> 40) & 0xFF),
        static_cast<uint8_t>((value >> 32) & 0xFF),
        static_cast<uint8_t>((value >> 24) & 0xFF),
        static_cast<uint8_t>((value >> 16) & 0xFF),
        static_cast<uint8_t>((value >> 8) & 0xFF),
        static_cast<uint8_t>(value & 0xFF)
    };
}

References kcenon::network::protocols::quic::varint_max.

Referenced by kcenon::network::protocols::quic::frame_builder::append_varint(), and kcenon::network::protocols::quic::packet_builder::build_initial().

Here is the caller graph for this function:

◆ encode_with_length()

auto kcenon::network::protocols::quic::varint::encode_with_length	(	uint64_t	value,
		size_t	min_length ) -> Result<std::vector<uint8_t>>

staticnodiscard

Encode with minimum length requirement.

Parameters

value	Value to encode
min_length	Minimum encoded length (1, 2, 4, or 8)

Returns: Result containing encoded bytes or error if value doesn't fit or min_length is invalid

Definition at line 57 of file varint.cpp.

{
    // Validate min_length
    if (min_length != 1 && min_length != 2 && min_length != 4 && min_length != 8)
    {
        return error<std::vector<uint8_t>>(
            error_codes::common_errors::invalid_argument,
            "Invalid minimum length",
            "quic::varint",
            "min_length must be 1, 2, 4, or 8"
        );
    }
 
    // Check if value fits in the requested length
    uint64_t max_for_length = 0;
    switch (min_length)
    {
        case 1: max_for_length = max_1byte; break;
        case 2: max_for_length = max_2byte; break;
        case 4: max_for_length = max_4byte; break;
        case 8: max_for_length = max_8byte; break;
        default: break;
    }
 
    // Find the actual minimum length needed
    size_t actual_length = encoded_length(value);
 
    // Use the larger of the two
    size_t use_length = (min_length > actual_length) ? min_length : actual_length;
 
    // If the requested min_length is smaller than needed, the value won't fit
    // But we use the larger length, so this is fine
 
    // Check if value exceeds maximum encodable
    if (value > varint_max)
    {
        return error<std::vector<uint8_t>>(
            error_codes::common_errors::invalid_argument,
            "Value exceeds maximum",
            "quic::varint",
            "Value exceeds 2^62 - 1"
        );
    }
 
    // Encode with the determined length
    std::vector<uint8_t> result;
    switch (use_length)
    {
        case 1:
            result = {static_cast<uint8_t>(value)};
            break;
 
        case 2:
            result = {
                static_cast<uint8_t>(prefix_2byte | ((value >> 8) & value_mask)),
                static_cast<uint8_t>(value & 0xFF)
            };
            break;
 
        case 4:
            result = {
                static_cast<uint8_t>(prefix_4byte | ((value >> 24) & value_mask)),
                static_cast<uint8_t>((value >> 16) & 0xFF),
                static_cast<uint8_t>((value >> 8) & 0xFF),
                static_cast<uint8_t>(value & 0xFF)
            };
            break;
 
        case 8:
            result = {
                static_cast<uint8_t>(prefix_8byte | ((value >> 56) & value_mask)),
                static_cast<uint8_t>((value >> 48) & 0xFF),
                static_cast<uint8_t>((value >> 40) & 0xFF),
                static_cast<uint8_t>((value >> 32) & 0xFF),
                static_cast<uint8_t>((value >> 24) & 0xFF),
                static_cast<uint8_t>((value >> 16) & 0xFF),
                static_cast<uint8_t>((value >> 8) & 0xFF),
                static_cast<uint8_t>(value & 0xFF)
            };
            break;
 
        default:
            break;
    }
 
    return ok(std::move(result));
}

References kcenon::network::protocols::quic::error, kcenon::network::error_codes::common_errors::invalid_argument, kcenon::network::ok(), and kcenon::network::protocols::quic::varint_max.

Here is the call graph for this function:

◆ encoded_length()

static constexpr auto kcenon::network::protocols::quic::varint::encoded_length ( uint64_t value ) -> size_t

inlinestaticnodiscardconstexprnoexcept

Get the number of bytes needed to encode a value.

Parameters

value Value to check

Returns: Encoded length in bytes (1, 2, 4, or 8)

Definition at line 72 of file varint.h.

        {
            if (value <= 63)
            {
                return 1;
            }
            if (value <= 16383)
            {
                return 2;
            }
            if (value <= 1073741823)
            {
                return 4;
            }
            return 8;
        }

◆ is_valid()

static constexpr auto kcenon::network::protocols::quic::varint::is_valid ( uint64_t value ) -> bool

inlinestaticnodiscardconstexprnoexcept

Check if a value can be encoded as a varint.

Parameters

value Value to check

Returns: true if value <= varint_max

Definition at line 104 of file varint.h.

        {
            return value <= varint_max;
        }

References kcenon::network::protocols::quic::varint_max.

◆ length_from_prefix()

static constexpr auto kcenon::network::protocols::quic::varint::length_from_prefix ( uint8_t first_byte ) -> size_t

inlinestaticnodiscardconstexprnoexcept

Get encoded length from the first byte's prefix.

Parameters

first_byte First byte of encoded varint

Returns: Encoded length in bytes (1, 2, 4, or 8)

Definition at line 94 of file varint.h.

        {
            return size_t{1} << (first_byte >> 6);
        }

Member Data Documentation

◆ max_1byte

uint64_t kcenon::network::protocols::quic::varint::max_1byte = 63

src/internal/protocols/quic/varint.h
src/protocols/quic/varint.cpp

Static Public Member Functions

Static Public Attributes

Static Private Attributes

Detailed Description

Member Function Documentation

◆ decode()

◆ encode()

◆ encode_with_length()

◆ encoded_length()

◆ is_valid()

◆ length_from_prefix()

Member Data Documentation

◆ max_1byte

◆ max_2byte

◆ max_4byte

◆ max_8byte

◆ prefix_1byte

◆ prefix_2byte

◆ prefix_4byte

◆ prefix_8byte

◆ prefix_mask

◆ value_mask