nish/net/quic-conn-params

QUIC's transport parameters (RFC 9000 §18), the bytes each endpoint carries in TLS's quic_transport_parameters extension (RFC 9001 §8.2), encoded and parsed.

import {
  QUIC_MIN_UDP_PAYLOAD,
  QUIC_TP_ACK_DELAY_EXPONENT,
  QUIC_TP_ACTIVE_CONNECTION_ID_LIMIT,
  QUIC_TP_DISABLE_ACTIVE_MIGRATION,
  QUIC_TP_INITIAL_MAX_DATA,
  QUIC_TP_INITIAL_MAX_STREAMS_BIDI,
  QUIC_TP_INITIAL_MAX_STREAMS_UNI,
  QUIC_TP_INITIAL_MAX_STREAM_DATA_BIDI_LOCAL,
  QUIC_TP_INITIAL_MAX_STREAM_DATA_BIDI_REMOTE,
  QUIC_TP_INITIAL_MAX_STREAM_DATA_UNI,
  QUIC_TP_INITIAL_SCID,
  QUIC_TP_MAX_ACK_DELAY,
  QUIC_TP_MAX_DATAGRAM_FRAME_SIZE,
  QUIC_TP_MAX_IDLE_TIMEOUT,
  QUIC_TP_MAX_UDP_PAYLOAD_SIZE,
  QUIC_TP_ORIGINAL_DCID,
  QUIC_TP_PREFERRED_ADDRESS,
  QUIC_TP_RETRY_SCID,
  QUIC_TP_STATELESS_RESET_TOKEN,
  QuicTransportParameters,
  quicEncodeTransportParameters,
  quicEncodeTransportParametersInto,
  quicParseTransportParameters,
  quicParseTransportParametersInto,
} from "nish/net/quic-conn-params";
import { QuicTransportParameters, quicEncodeTransportParameters,
         quicParseTransportParameters } from "nish/net/quic-conn-params";

const mine: QuicTransportParameters = new QuicTransportParameters()
mine.initialMaxData = 65536
const bytes: u8[] = quicEncodeTransportParameters(mine)   // for TlsServerConfig
// bytes is [0x04, 0x04, 0x80, 0x01, 0x00, 0x00]: initial_max_data, length 4, 65536
const theirs: QuicTransportParameters = quicParseTransportParameters(bytes, false)
if (theirs.error !== 0) {
  // close the connection with theirs.error; theirs.errorParameter names the parameter
}
Defaults

A QuicTransportParameters starts at every parameter's default (§18.2), so a parse leaves a parameter the peer did not send at the value the RFC says it then has. The encoder writes a parameter only when it differs from that default, plus the connection IDs, which have none.

What a parse refuses.

Each of these is a TRANSPORT_PARAMETER_ERROR (§7.4, §18.2): an ID or a length that does not fit, a parameter running past the bytes, a known parameter sent twice, a varint-valued parameter whose value is not exactly one varint, disable_active_migration with a value, a server-only parameter from a client (original_destination_connection_id, preferred_address, retry_source_connection_id, stateless_reset_token), a stateless reset token that is not 16 bytes, a connection ID over 20 bytes, max_udp_payload_size below 1200, ack_delay_exponent above 20, max_ack_delay at 2^14 or above, active_connection_id_limit below 2, and a stream count above 2^60.

Unknown parameters, the reserved ones (31 × N + 27) among them, are skipped, as §18.1 asks; a second copy of an unknown one is not noticed. Whether initial_source_connection_id is present and right is the connection's check, because it needs the packet the ID came in.

Provenance

Written from RFC 9000 §18, in this module's own structure; nothing here is ported from another implementation. Private names carry the quicParams prefix (docs/wp26-stdlib.md §3e).

Functions

quicEncodeTransportParameters

The transport parameters p as the quic_transport_parameters extension's body (§18): each parameter as its ID, its length and its value, in ID order, every varint-valued one only when it is not its default, every byte-valued one only when its has* flag is set, and disable_active_migration only when true. Nothing is checked: these are this endpoint's own values, and a value no varint holds is left out.

const quicEncodeTransportParameters: (
  p: QuicTransportParameters,
) => u8[]
pQuicTransportParametersrequired

This endpoint's parameters, only read.

returnsu8[]

A new array holding the extension body; empty when every parameter is at its default.

quicEncodeTransportParametersInto

quicEncodeTransportParameters into out, which is emptied first: the encoding is pushed into the room the array already has, so a connection slot that keeps one array for its parameters grows it only when they outgrow every earlier connection's.

const quicEncodeTransportParametersInto: (
  p: QuicTransportParameters,
  out: u8[],
) => void
pQuicTransportParametersrequired

This endpoint's parameters, only read.

outu8[]required

The array the extension body replaces the contents of.

quicParseTransportParameters

Parses the body of a quic_transport_parameters extension. fromServer says who sent it, which decides whether the server-only parameters are allowed. The answer's error is QUIC_ERROR_NO_ERROR, or QUIC_ERROR_TRANSPORT_PARAMETER for any of the breaks the module header lists, with errorParameter naming the parameter; on an error the other fields hold what was read so far and are not to be used.

const quicParseTransportParameters: (
  bytes: u8[],
  fromServer: boolean,
) => QuicTransportParameters
bytesu8[]required

The extension body as the peer sent it, only read.

fromServerbooleanrequired

True when the peer is the server, so that the server-only parameters are allowed.

returnsQuicTransportParameters

A new QuicTransportParameters; read its error before any other field.

quicParseTransportParametersInto

quicParseTransportParameters into p, which is set back to every default first, its byte-valued fields emptied and refilled in the room their arrays have: a connection slot parses each client's parameters into one object of its own. Answers p.

const quicParseTransportParametersInto: (
  p: QuicTransportParameters,
  bytes: u8[],
  fromServer: boolean,
) => QuicTransportParameters
pQuicTransportParametersrequired

The object to overwrite with the parsed parameters and the verdict in error.

bytesu8[]required

The extension body as the peer sent it, only read.

fromServerbooleanrequired

True when the peer is the server, so that the server-only parameters are allowed.

returnsQuicTransportParameters

p itself; read its error before any other field.

Classes

QuicTransportParameters

One endpoint's transport parameters. Every field starts at the default §18.2 gives it, and the connection IDs and token start empty with their has* flag false. preferredAddress is kept as the bytes the server sent, since this side never acts on it. error is what a parse answers: QUIC_ERROR_NO_ERROR, or QUIC_ERROR_TRANSPORT_PARAMETER with errorParameter the ID of the parameter at fault (-1 when the bytes did not frame).

class QuicTransportParameters
Member
new QuicTransportParameters() Makes the parameters an endpoint has before it sets or reads any: §18.2's defaults, every connection ID and token empty.
ackDelayExponent: i64 ack_delay_exponent: the power of two an ACK frame's delay is scaled by, at most 20; 3 by default.
activeConnectionIdLimit: i64 active_connection_id_limit: how many of its peer's connection IDs the sender keeps, at least 2.
disableActiveMigration: boolean disable_active_migration: the sender does not support active connection migration (RFC 9000 §9) from the address the handshake used.
error: i64 What the last parse answered: QUIC_ERROR_NO_ERROR, or QUIC_ERROR_TRANSPORT_PARAMETER with errorParameter set.
errorParameter: i64 The ID of the parameter a failed parse is about, or -1 when the bytes did not frame; read beside error.
hasInitialScid: boolean Whether initialScid was set or read; an empty ID is a value, so its length cannot say.
hasOriginalDcid: boolean Whether originalDcid was set or read; an empty ID is a value, so its length cannot say.
hasPreferredAddress: boolean Whether preferredAddress was set or read.
hasRetryScid: boolean Whether retryScid was set or read; an empty ID is a value, so its length cannot say.
hasStatelessResetToken: boolean Whether statelessResetToken was set or read.
initialMaxData: i64 initial_max_data: the connection's first receive credit, in bytes, across every stream.
initialMaxStreamDataBidiLocal: i64 initial_max_stream_data_bidi_local: the first credit, in bytes, on a bidirectional stream the sender opens.
initialMaxStreamDataBidiRemote: i64 initial_max_stream_data_bidi_remote: the first credit, in bytes, on a bidirectional stream its peer opens.
initialMaxStreamDataUni: i64 initial_max_stream_data_uni: the first credit, in bytes, on a unidirectional stream its peer opens.
initialMaxStreamsBidi: i64 initial_max_streams_bidi: how many bidirectional streams the peer may open at first, at most 2^60.
initialMaxStreamsUni: i64 initial_max_streams_uni: how many unidirectional streams the peer may open at first, at most 2^60.
initialScid: u8[] initial_source_connection_id: the Source Connection ID of the sender's first Initial packet.
maxAckDelay: i64 max_ack_delay, in milliseconds: how long the sender may hold an acknowledgement, below 2^14; 25 by default.
maxDatagramFrameSize: i64 RFC 9221's max_datagram_frame_size: 0, the default, for no DATAGRAM frames.
maxIdleTimeout: i64 max_idle_timeout, in milliseconds; 0, the default, for no idle timeout.
maxUdpPayloadSize: i64 max_udp_payload_size: the largest UDP payload the sender takes, at least 1200 bytes; 65527 by default.
originalDcid: u8[] original_destination_connection_id: the client's first Destination Connection ID; server only.
preferredAddress: u8[] preferred_address, kept as the bytes the server sent, since this side never acts on it; server only.
retryScid: u8[] retry_source_connection_id: the Source Connection ID of the server's Retry; server only.
statelessResetToken: u8[] stateless_reset_token: 16 bytes that end a stateless reset for the server's connection ID; server only.

Limits

1,200

QUIC_MIN_UDP_PAYLOAD: i64

The smallest max_udp_payload_size allowed, and every QUIC path's minimum datagram (RFC 9000 §14).

Constants

0x0a

QUIC_TP_ACK_DELAY_EXPONENT: i32

ack_delay_exponent: an ACK Delay field counts units of 2^this microseconds; at most 20, default 3.

0x0e

QUIC_TP_ACTIVE_CONNECTION_ID_LIMIT: i32

active_connection_id_limit: how many of the peer's connection IDs the sender keeps; at least 2, the default.

0x0c

QUIC_TP_DISABLE_ACTIVE_MIGRATION: i32

disable_active_migration: present, with no value, when the sender takes no connection migration.

0x04

QUIC_TP_INITIAL_MAX_DATA: i32

initial_max_data: the connection-wide flow-control limit, in bytes.

0x08

QUIC_TP_INITIAL_MAX_STREAMS_BIDI: i32

initial_max_streams_bidi: how many bidirectional streams the peer may open; at most 2^60.

0x09

QUIC_TP_INITIAL_MAX_STREAMS_UNI: i32

initial_max_streams_uni: how many unidirectional streams the peer may open; at most 2^60.

0x05

QUIC_TP_INITIAL_MAX_STREAM_DATA_BIDI_LOCAL: i32

initial_max_stream_data_bidi_local: the flow-control limit, in bytes, for bidirectional streams the sender opens.

0x06

QUIC_TP_INITIAL_MAX_STREAM_DATA_BIDI_REMOTE: i32

initial_max_stream_data_bidi_remote: the flow-control limit, in bytes, for bidirectional streams the peer opens.

0x07

QUIC_TP_INITIAL_MAX_STREAM_DATA_UNI: i32

initial_max_stream_data_uni: the flow-control limit, in bytes, for unidirectional streams the peer opens.

0x0f

QUIC_TP_INITIAL_SCID: i32

initial_source_connection_id: the Source Connection ID of the sender's first Initial.

0x0b

QUIC_TP_MAX_ACK_DELAY: i32

max_ack_delay: the longest the sender delays an acknowledgement, in milliseconds; below 2^14, default 25.

0x20

QUIC_TP_MAX_DATAGRAM_FRAME_SIZE: i32

max_datagram_frame_size (RFC 9221 §3): the largest DATAGRAM frame, type and Length included, the sender takes; absent or 0, it takes none.

0x01

QUIC_TP_MAX_IDLE_TIMEOUT: i32

max_idle_timeout, in milliseconds; 0 or absent for no idle timeout.

0x03

QUIC_TP_MAX_UDP_PAYLOAD_SIZE: i32

max_udp_payload_size: the largest UDP payload, in bytes, the sender takes; at least 1200, default 65527.

0x00

QUIC_TP_ORIGINAL_DCID: i32

original_destination_connection_id: the Destination Connection ID of the client's first Initial; server only.

0x0d

QUIC_TP_PREFERRED_ADDRESS: i32

preferred_address: an address the server would have the client move to; server only.

0x10

QUIC_TP_RETRY_SCID: i32

retry_source_connection_id: the Source Connection ID of the server's Retry, when it sent one; server only.

0x02

QUIC_TP_STATELESS_RESET_TOKEN: i32

stateless_reset_token: the 16-byte token for the server's first connection ID; server only.