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
}
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.
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.
quicParseTransportParameters
Parses the body of a quic_transport_parameters extension.
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.
QuicTransportParameters
One endpoint's transport parameters.
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[]
pQuicTransportParametersrequiredThis 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
pQuicTransportParametersrequiredThis endpoint's parameters, only read.
outu8[]requiredThe 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[]requiredThe extension body as the peer sent it, only read.
fromServerbooleanrequiredTrue when the peer is the server, so that the server-only parameters are allowed.
returnsQuicTransportParametersA 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
pQuicTransportParametersrequiredThe object to overwrite with the parsed parameters and the verdict in error.
bytesu8[]requiredThe extension body as the peer sent it, only read.
fromServerbooleanrequiredTrue when the peer is the server, so that the server-only parameters are allowed.
returnsQuicTransportParametersp 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.

