nish/net/quic-frame

The frames of QUIC version 1 (RFC 9000 §19) and RFC 9221's DATAGRAM, read from a decrypted packet payload and written into one, and the transport error codes a connection closes with (§20.1).

import {
  QUIC_ERROR_AEAD_LIMIT_REACHED,
  QUIC_ERROR_APPLICATION,
  QUIC_ERROR_CONNECTION_ID_LIMIT,
  QUIC_ERROR_CONNECTION_REFUSED,
  QUIC_ERROR_CRYPTO,
  QUIC_ERROR_CRYPTO_BUFFER_EXCEEDED,
  QUIC_ERROR_FINAL_SIZE,
  QUIC_ERROR_FLOW_CONTROL,
  QUIC_ERROR_FRAME_ENCODING,
  QUIC_ERROR_INTERNAL,
  QUIC_ERROR_INVALID_TOKEN,
  QUIC_ERROR_KEY_UPDATE,
  QUIC_ERROR_NO_ERROR,
  QUIC_ERROR_NO_VIABLE_PATH,
  QUIC_ERROR_PROTOCOL_VIOLATION,
  QUIC_ERROR_STREAM_LIMIT,
  QUIC_ERROR_STREAM_STATE,
  QUIC_ERROR_TRANSPORT_PARAMETER,
  QUIC_FRAME_ACK,
  QUIC_FRAME_ACK_ECN,
  QUIC_FRAME_CONNECTION_CLOSE,
  QUIC_FRAME_CONNECTION_CLOSE_APP,
  QUIC_FRAME_CRYPTO,
  QUIC_FRAME_DATAGRAM,
  QUIC_FRAME_DATAGRAM_LENGTH,
  QUIC_FRAME_DATA_BLOCKED,
  QUIC_FRAME_HANDSHAKE_DONE,
  QUIC_FRAME_MAX_ACK_RANGES,
  QUIC_FRAME_MAX_DATA,
  QUIC_FRAME_MAX_STREAMS_BIDI,
  QUIC_FRAME_MAX_STREAMS_UNI,
  QUIC_FRAME_MAX_STREAM_DATA,
  QUIC_FRAME_NEW_CONNECTION_ID,
  QUIC_FRAME_NEW_TOKEN,
  QUIC_FRAME_PADDING,
  QUIC_FRAME_PATH_CHALLENGE,
  QUIC_FRAME_PATH_RESPONSE,
  QUIC_FRAME_PING,
  QUIC_FRAME_RESET_STREAM,
  QUIC_FRAME_RETIRE_CONNECTION_ID,
  QUIC_FRAME_STOP_SENDING,
  QUIC_FRAME_STREAM,
  QUIC_FRAME_STREAMS_BLOCKED_BIDI,
  QUIC_FRAME_STREAMS_BLOCKED_UNI,
  QUIC_FRAME_STREAM_DATA_BLOCKED,
  QUIC_PATH_DATA_SIZE,
  QUIC_RESET_TOKEN_SIZE,
  QuicFrame,
  quicAckEcnSize,
  quicAckSize,
  quicCryptoOverhead,
  quicDatagramSize,
  quicFrameAckEliciting,
  quicFrameAllowed,
  quicParseFrame,
  quicPushAck,
  quicPushAckEcn,
  quicPushConnectionClose,
  quicPushCrypto,
  quicPushNewConnectionId,
  quicPushNewToken,
  quicPushPadding,
  quicPushPathData,
  quicPushStream,
  quicPushStreamError,
  quicPushStreamValue,
  quicPushTypeOnly,
  quicPushValue,
  quicPutAck,
  quicPutAckEcn,
  quicPutConnectionClose,
  quicPutCrypto,
  quicPutDatagram,
  quicPutNewConnectionId,
  quicPutPadding,
  quicPutPathData,
  quicPutStream,
  quicPutStreamError,
  quicPutStreamValue,
  quicPutTypeOnly,
  quicPutValue,
  quicStreamOverhead,
} from "nish/net/quic-frame";
import { QuicFrame, quicParseFrame, quicPushAck, QUIC_FRAME_CRYPTO } from "nish/net/quic-frame";

const frame = new QuicFrame();                       // one per connection, reused
let at: i32 = 0;
while (at < toI32(payload.length)) {
  const error: i64 = quicParseFrame(frame, payload, at, toI32(payload.length));
  if (error !== 0) { … close the connection with `error` … }
  if (frame.type === QUIC_FRAME_CRYPTO) { … payload[frame.dataStart .. + frame.dataLength) … }
  at = frame.end;
}
Coverage

Every frame type of RFC 9000 is read, 0x00 to 0x1e, and RFC 9221's DATAGRAM, 0x30 and 0x31, so a type outside those is the one parse error a well-formed packet cannot produce.

What a frame means is nish/net/quic's: this module checks only what §19 says of the encoding itself, and answers the transport error the RFC names for each break — QUIC_ERROR_FRAME_ENCODING for a truncated field, a length past the packet, an ACK range below packet number zero, an offset past 2^62 − 1, a stream count past 2^60, an empty NEW_TOKEN, a connection ID outside 1 to 20 bytes or a Retire Prior To above its own sequence number; QUIC_ERROR_PROTOCOL_VIOLATION for a frame type spelled in more bytes than it needs (§12.4).

Every read is bounds-checked against the window the caller gives, so nothing a peer sends can make this module panic.

No copy of the bulk

A CRYPTO, STREAM or DATAGRAM frame's data, a NEW_TOKEN's token, a PATH_CHALLENGE's eight bytes and a CONNECTION_CLOSE's reason are left in the payload and described by dataStart and dataLength, and a NEW_CONNECTION_ID's ID and token by windows of their own, so a connection reassembles straight from the packet. One QuicFrame is reused for every frame of every packet: quicParseFrame overwrites every field it reads and resets the rest, and stores nothing but numbers, so a payload made inside an arena block can be read inside it.

Writers

They come in two forms. A put writer writes one frame into a caller's buffer at an offset, before an end, and answers the offset past it, or -1 with nothing written; a push writer appends one to an array and answers whether it could, by growing the array and calling the put form, so each frame has one encoder. Either refuses a value no varint holds or a window outside the array given. Their inputs are this endpoint's own, never a peer's. quicFrameAllowed is RFC 9000 §12.4's table of which frames each packet type may carry.

Written from RFC 9000 §12.4, §19 and §20 and RFC 9221 §4, in this module's own structure; nothing here is ported from another implementation. Private names carry the quicFrame prefix because a std/ module's private functions share the importing program's flat symbol namespace (docs/wp26-stdlib.md §3e).

Functions

quicAckEcnSize

The size of the ACK_ECN frame quicPutAckEcn writes: the ACK frame quicAckSize sizes, then the three ECN counts. Answers 0 where quicAckSize does, or when a count is negative or above 2^62-1.

const quicAckEcnSize: (
  ranges: i64[],
  rangeCount: i32,
  ackDelay: i64,
  ect0: i64,
  ect1: i64,
  ce: i64,
) => i32
rangesi64[]required

Packet number pairs laid out flat, [smallest, largest] for each range, highest range first.

rangeCounti32required

How many pairs to read from the front of ranges.

ackDelayi64required

The ACK Delay field, already scaled by this endpoint's ack_delay_exponent.

ect0i64required

The ECT(0) count: packets received in this space marked ECT(0).

ect1i64required

The ECT(1) count: packets received in this space marked ECT(1).

cei64required

The ECN-CE count: packets received in this space marked CE.

returnsi32

The frame's size in bytes, or 0 when quicPutAckEcn would refuse these arguments.

quicAckSize

The size of the ACK frame quicPutAck writes for these ranges, or 0 when it would refuse them: no ranges, ranges out of order or touching, a pair the array does not hold, or a value no varint holds.

const quicAckSize: (
  ranges: i64[],
  rangeCount: i32,
  ackDelay: i64,
) => i32
rangesi64[]required

Packet number pairs laid out flat, [smallest, largest] for each range, highest range first.

rangeCounti32required

How many pairs to read from the front of ranges; the rest of the array is ignored.

ackDelayi64required

The ACK Delay field, already scaled by this endpoint's ack_delay_exponent.

returnsi32

The frame's size in bytes, or 0 when quicPutAck would refuse these arguments.

quicCryptoOverhead

The bytes a CRYPTO frame's header takes for length bytes of data at offset: the type, the offset and the length.

const quicCryptoOverhead: (offset: i64, length: i32) => i32
offseti64required

The crypto stream offset, in bytes, of the frame's first data byte, up to 2^62 − 1.

lengthi32required

How many data bytes the frame carries.

returnsi32

The header's size in bytes, not counting the data, which is what a sender subtracts from a packet's room to see how much data fits.

quicDatagramSize

The size of the DATAGRAM frame quicPutDatagram writes for a payload of length bytes: the type, the Length and the payload. This is the size RFC 9221 §3 holds to max_datagram_frame_size.

const quicDatagramSize: (length: i32) => i32
lengthi32required

The payload's size in bytes.

returnsi32

The whole frame's size in bytes.

quicFrameAckEliciting

Whether a frame of type asks for an acknowledgement (RFC 9000 §13.2): every frame but ACK, PADDING and CONNECTION_CLOSE.

const quicFrameAckEliciting: (type: i32) => boolean
typei32required

The frame type as quicParseFrame answers it.

returnsboolean

True when a packet holding this frame is ack-eliciting, which is what decides whether the peer must acknowledge it promptly.

quicFrameAllowed

Whether a frame of type may appear in a packet of packetType (RFC 9000 §12.4, Table 3). Initial and Handshake packets carry only PADDING, PING, ACK, CRYPTO and the transport CONNECTION_CLOSE; a 0-RTT packet anything but ACK, CRYPTO, NEW_TOKEN, HANDSHAKE_DONE and the retire and response frames a client cannot have a reason to send yet; a 1-RTT packet anything.

const quicFrameAllowed: (
  type: i32,
  packetType: i32,
) => boolean
typei32required

The frame type as quicParseFrame answers it in QuicFrame.type, every STREAM type as QUIC_FRAME_STREAM.

packetTypei32required

The packet's QUIC_PACKET_* type from nish/net/quic-packet, QUIC_PACKET_SHORT for 1-RTT.

returnsboolean

True when §12.4 permits the frame there; false when it does not permit that frame in that packet type, and for a packet type that carries no frames, such as Retry.

quicParseFrame

Reads the frame starting at payload[at], inside payload[at .. end), into frame, which is reset first, and answers 0 or the transport error the RFC names for the break (see the module header). On 0, frame.end is where the next frame starts; after an error the packet is not to be read further, and frame.type still holds the type when it was read, which is what CONNECTION_CLOSE reports. A window outside payload is QUIC_ERROR_INTERNAL, the caller's fault rather than the peer's.

const quicParseFrame: (
  frame: QuicFrame,
  payload: u8[],
  at: i32,
  end: i32,
) => i64
frameQuicFramerequired

The frame to fill, reused across frames and packets; its windows (dataStart and the like) are offsets into payload, so they mean something only while payload is unchanged.

payloadu8[]required

The decrypted packet payload, as the peer sent it; only read, never kept.

ati32required

The offset of the frame's first byte, its type.

endi32required

One past the last byte the frame may use, normally the payload's end; a frame reaching past it is QUIC_ERROR_FRAME_ENCODING.

returnsi64

QUIC_ERROR_NO_ERROR (0) for a good frame, otherwise the QUIC_ERROR_* code to close the connection with.

quicPushAck

Appends the ACK frame quicPutAck writes. Answers false, appending nothing, where it refuses.

const quicPushAck: (
  out: u8[],
  ranges: i64[],
  rangeCount: i32,
  ackDelay: i64,
) => boolean
outu8[]required

The bytes to append the frame to.

rangesi64[]required

Packet number pairs laid out flat, [smallest, largest] for each range, highest range first.

rangeCounti32required

How many pairs to read from the front of ranges.

ackDelayi64required

The ACK Delay field, already scaled by this endpoint's ack_delay_exponent.

returnsboolean

True when the frame was appended.

quicPushAckEcn

Appends the ACK_ECN frame quicPutAckEcn writes. Answers false, appending nothing, where it refuses.

const quicPushAckEcn: (
  out: u8[],
  ranges: i64[],
  rangeCount: i32,
  ackDelay: i64,
  ect0: i64,
  ect1: i64,
  ce: i64,
) => boolean
outu8[]required

The bytes to append the frame to.

rangesi64[]required

Packet number pairs laid out flat, [smallest, largest] for each range, highest range first.

rangeCounti32required

How many pairs to read from the front of ranges.

ackDelayi64required

The ACK Delay field, already scaled by this endpoint's ack_delay_exponent.

ect0i64required

The ECT(0) count.

ect1i64required

The ECT(1) count.

cei64required

The ECN-CE count.

returnsboolean

True when the frame was appended.

quicPushConnectionClose

Appends the frame quicPutConnectionClose writes. Answers false, appending nothing, where it refuses.

const quicPushConnectionClose: (
  out: u8[],
  application: boolean,
  errorCode: i64,
  frameType: i64,
  reason: u8[],
) => boolean
outu8[]required

The bytes to append the frame to.

applicationbooleanrequired

Whether the close is the application's (0x1d) rather than the transport's (0x1c).

errorCodei64required

A QUIC_ERROR_* code for a transport close, the application's own code otherwise.

frameTypei64required

The frame type that caused a transport error, 0 when none did; ignored when application.

reasonu8[]required

The whole array is the reason phrase, UTF-8, possibly empty; copied, not kept.

returnsboolean

True when the frame was appended.

quicPushCrypto

Appends the CRYPTO frame quicPutCrypto writes. Answers false, appending nothing, where it refuses.

const quicPushCrypto: (
  out: u8[],
  offset: i64,
  data: u8[],
  from: i32,
  length: i32,
) => boolean
outu8[]required

The bytes to append the frame to.

offseti64required

The crypto stream offset, in bytes, of the first byte carried.

datau8[]required

The handshake bytes to take the window from; copied, not kept.

fromi32required

The offset in data of the first byte to carry.

lengthi32required

How many bytes to carry.

returnsboolean

True when the frame was appended.

quicPushNewConnectionId

Appends a NEW_CONNECTION_ID frame (§19.15). Answers false for a connection ID outside 1 to 20 bytes, a reset token that is not 16 bytes, a Retire Prior To above the sequence number, or a value no varint holds.

const quicPushNewConnectionId: (
  out: u8[],
  sequence: i64,
  retirePriorTo: i64,
  connectionId: u8[],
  resetToken: u8[],
) => boolean
outu8[]required

The bytes to append the frame to.

sequencei64required

The sequence number this endpoint gives the new connection ID.

retirePriorToi64required

The peer is to retire every connection ID of a lower sequence number; 0 retires none.

connectionIdu8[]required

The new ID, the whole array; copied, not kept.

resetTokenu8[]required

The 16-byte stateless reset token tied to the ID; copied, not kept.

returnsboolean

True when the frame was appended; false, appending nothing, otherwise.

quicPushNewToken

Appends a NEW_TOKEN frame (§19.7) carrying token. Answers false for an empty token, which §19.7 forbids.

const quicPushNewToken: (out: u8[], token: u8[]) => boolean
outu8[]required

The bytes to append the frame to.

tokenu8[]required

The whole array is the token the client is to present later; copied, not kept.

returnsboolean

True when the frame was appended; false, appending nothing, for an empty token.

quicPushPadding

Appends count PADDING frames, which are count zero bytes. A count below one appends nothing.

const quicPushPadding: (out: u8[], count: i32) => void
outu8[]required

The bytes to grow, such as a packet payload being built.

counti32required

How many bytes of padding to append.

quicPushPathData

Appends the frame quicPutPathData writes. Answers false, appending nothing, where it refuses.

const quicPushPathData: (
  out: u8[],
  type: i32,
  data: u8[],
  from: i32,
) => boolean
outu8[]required

The bytes to append the frame to.

typei32required

QUIC_FRAME_PATH_CHALLENGE or QUIC_FRAME_PATH_RESPONSE.

datau8[]required

Holds the eight bytes to carry.

fromi32required

The offset in data of the first of the eight bytes.

returnsboolean

True when the frame was appended.

quicPushStream

Appends a STREAM frame (§19.8) carrying data[from .. from + length) on streamId at offset, with FIN when fin, as quicPutStream writes it. Answers false, appending nothing, for a window outside data, a stream ID that is not a varint or an end past 2^62 − 1.

const quicPushStream: (
  out: u8[],
  streamId: i64,
  offset: i64,
  data: u8[],
  from: i32,
  length: i32,
  fin: boolean,
) => boolean
outu8[]required

The bytes to append the frame to.

streamIdi64required

The stream the data belongs to.

offseti64required

The stream offset, in bytes, of the first byte carried.

datau8[]required

The bytes to take the window from; copied, not kept, and not read as a ring.

fromi32required

The offset in data of the first byte to carry.

lengthi32required

How many bytes to carry; 0 for a frame that only carries FIN.

finbooleanrequired

Whether these bytes end the stream.

returnsboolean

True when the frame was appended.

quicPushStreamError

Appends the frame quicPutStreamError writes. Answers false, appending nothing, where it refuses.

const quicPushStreamError: (
  out: u8[],
  streamId: i64,
  errorCode: i64,
  finalSize: i64,
) => boolean
outu8[]required

The bytes to append the frame to.

streamIdi64required

The stream being reset or asked to stop.

errorCodei64required

The application's error code for why.

finalSizei64required

The stream's final size in bytes for RESET_STREAM, or -1 for STOP_SENDING.

returnsboolean

True when the frame was appended.

quicPushStreamValue

Appends the frame quicPutStreamValue writes. Answers false, appending nothing, where it refuses.

const quicPushStreamValue: (
  out: u8[],
  type: i32,
  streamId: i64,
  value: i64,
) => boolean
outu8[]required

The bytes to append the frame to.

typei32required

QUIC_FRAME_MAX_STREAM_DATA or QUIC_FRAME_STREAM_DATA_BLOCKED.

streamIdi64required

The stream the limit is for.

valuei64required

The stream's limit in bytes.

returnsboolean

True when the frame was appended.

quicPushTypeOnly

Appends a frame that is its type alone: PING or HANDSHAKE_DONE. Answers false for another type.

const quicPushTypeOnly: (out: u8[], type: i32) => boolean
outu8[]required

The bytes to append the frame's one byte to.

typei32required

QUIC_FRAME_PING or QUIC_FRAME_HANDSHAKE_DONE.

returnsboolean

True when the frame was appended; false, appending nothing, for any other type.

quicPushValue

Appends the frame quicPutValue writes. Answers false, appending nothing, where it refuses.

const quicPushValue: (
  out: u8[],
  type: i32,
  value: i64,
) => boolean
outu8[]required

The bytes to append the frame to.

typei32required

One of the seven types quicPutValue writes.

valuei64required

What the type carries: bytes, a count of streams or a sequence number, as for quicPutValue.

returnsboolean

True when the frame was appended.

quicPutAck

Writes an ACK frame (§19.3) for the rangeCount pairs of ranges, each [smallest, largest], from the highest down and not touching (each pair's largest at least two below the smallest of the pair before it), with ackDelay already scaled by this endpoint's exponent. Answers -1, writing nothing, where quicAckSize answers 0 or the frame does not fit.

const quicPutAck: (
  buf: u8[],
  at: i32,
  end: i32,
  ranges: i64[],
  rangeCount: i32,
  ackDelay: i64,
) => i32
bufu8[]required

The buffer to write into.

ati32required

The offset of the frame's first byte.

endi32required

One past the last byte the frame may use.

rangesi64[]required

Packet number pairs laid out flat, [smallest, largest] for each range, highest range first.

rangeCounti32required

How many pairs to read from the front of ranges.

ackDelayi64required

The ACK Delay field, already scaled: microseconds shifted right by the exponent.

returnsi32

The offset past the frame, or -1 with nothing written. The frame is type 0x02, without ECN counts; quicPutAckEcn writes the 0x03 frame that carries them.

quicPutAckEcn

Writes an ACK_ECN frame (type 0x03, RFC 9000 §19.3.2): the ranges and ACK Delay quicPutAck writes, then the ECT(0), ECT(1) and ECN-CE counts a receiver keeps for the space (§13.4.1). Answers -1, writing nothing, where quicAckEcnSize answers 0 or the frame does not fit.

const quicPutAckEcn: (
  buf: u8[],
  at: i32,
  end: i32,
  ranges: i64[],
  rangeCount: i32,
  ackDelay: i64,
  ect0: i64,
  ect1: i64,
  ce: i64,
) => i32
bufu8[]required

The buffer to write into.

ati32required

The offset of the frame's first byte.

endi32required

One past the last byte the frame may use.

rangesi64[]required

Packet number pairs laid out flat, [smallest, largest] for each range, highest range first.

rangeCounti32required

How many pairs to read from the front of ranges.

ackDelayi64required

The ACK Delay field, already scaled: microseconds shifted right by the exponent.

ect0i64required

The ECT(0) count.

ect1i64required

The ECT(1) count.

cei64required

The ECN-CE count.

returnsi32

The offset past the frame, or -1 with nothing written.

quicPutConnectionClose

Writes a CONNECTION_CLOSE frame (§19.19): with application false the transport form 0x1c, carrying frameType, the type of the frame that caused the error (0 when none did); with application true the 0x1d form, which has no frame type. reason is the phrase, UTF-8, possibly empty. Answers -1 for a value no varint holds, or no room.

const quicPutConnectionClose: (
  buf: u8[],
  at: i32,
  end: i32,
  application: boolean,
  errorCode: i64,
  frameType: i64,
  reason: u8[],
) => i32
bufu8[]required

The buffer to write into.

ati32required

The offset of the frame's first byte.

endi32required

One past the last byte the frame may use.

applicationbooleanrequired

Whether the close is the application's (0x1d) rather than the transport's (0x1c).

errorCodei64required

A QUIC_ERROR_* code for a transport close, the application's own code otherwise.

frameTypei64required

The frame type that caused a transport error, 0 when none did; ignored when application.

reasonu8[]required

The whole array is the reason phrase; copied, not kept.

returnsi32

The offset past the frame, or -1 with nothing written.

quicPutCrypto

Writes a CRYPTO frame (§19.6) carrying data[from .. from + length) at stream offset offset. Answers -1, writing nothing, for a window outside data, an offset whose end passes 2^62 − 1, or no room.

const quicPutCrypto: (
  buf: u8[],
  at: i32,
  end: i32,
  offset: i64,
  data: u8[],
  from: i32,
  length: i32,
) => i32
bufu8[]required

The buffer to write into.

ati32required

The offset of the frame's first byte.

endi32required

One past the last byte the frame may use.

offseti64required

The crypto stream offset, in bytes, of the first byte carried.

datau8[]required

The handshake bytes to take the window from; copied, not kept.

fromi32required

The offset in data of the first byte to carry.

lengthi32required

How many bytes to carry.

returnsi32

The offset past the frame, or -1 with nothing written.

quicPutDatagram

Writes a DATAGRAM frame with a Length (type 0x31, RFC 9221 §4) carrying data[from .. from + length). Answers -1 for a window outside data or no room.

const quicPutDatagram: (
  buf: u8[],
  at: i32,
  end: i32,
  data: u8[],
  from: i32,
  length: i32,
) => i32
bufu8[]required

The buffer to write into.

ati32required

The offset of the frame's first byte.

endi32required

One past the last byte the frame may use.

datau8[]required

The payload's bytes; copied, not kept.

fromi32required

The offset in data of the payload's first byte.

lengthi32required

The payload's size in bytes.

returnsi32

The offset past the frame, or -1 with nothing written.

quicPutNewConnectionId

Writes a NEW_CONNECTION_ID frame (§19.15) for the first cidLength bytes of connectionId. Answers -1 for a connection ID outside 1 to 20 bytes or past the array, a reset token that is not 16 bytes, a Retire Prior To above the sequence number, a value no varint holds, or no room.

const quicPutNewConnectionId: (
  buf: u8[],
  at: i32,
  end: i32,
  sequence: i64,
  retirePriorTo: i64,
  connectionId: u8[],
  cidLength: i32,
  resetToken: u8[],
) => i32
bufu8[]required

The buffer to write into.

ati32required

The offset of the frame's first byte.

endi32required

One past the last byte the frame may use.

sequencei64required

The sequence number this endpoint gives the new connection ID.

retirePriorToi64required

The peer is to retire every connection ID of a lower sequence number; 0 retires none.

connectionIdu8[]required

The bytes of the new ID, which may be a longer buffer; copied, not kept.

cidLengthi32required

How many bytes of connectionId are the ID, 1 to 20.

resetTokenu8[]required

The 16-byte stateless reset token tied to the ID; copied, not kept.

returnsi32

The offset past the frame, or -1 with nothing written.

quicPutPadding

Writes count PADDING frames, zero bytes, into buf[at .. at + count), clamped to buf, and answers the offset past them.

const quicPutPadding: (
  buf: u8[],
  at: i32,
  count: i32,
) => i32
bufu8[]required

The buffer to write into.

ati32required

The offset of the first zero byte.

counti32required

How many zero bytes to write; fewer are written where buf ends first.

returnsi32

The offset past the last byte written, which is short of at + count when buf was too small and at itself when nothing could be written.

quicPutPathData

Writes a PATH_CHALLENGE or PATH_RESPONSE frame carrying the eight bytes data[from .. from + 8). Answers -1 for another type, a window outside data, or no room.

const quicPutPathData: (
  buf: u8[],
  at: i32,
  end: i32,
  type: i32,
  data: u8[],
  from: i32,
) => i32
bufu8[]required

The buffer to write into.

ati32required

The offset of the frame's first byte.

endi32required

One past the last byte the frame may use.

typei32required

QUIC_FRAME_PATH_CHALLENGE or QUIC_FRAME_PATH_RESPONSE.

datau8[]required

Holds the eight bytes: fresh random ones for a challenge, the challenge's own for a response.

fromi32required

The offset in data of the first of the eight bytes.

returnsi32

The offset past the frame, nine bytes on, or -1 with nothing written.

quicPutStream

Writes a STREAM frame (§19.8) carrying length bytes of data on streamId at offset, with FIN when fin. The data is read from data as a ring: byte k of it is data[(from + k) % data.length], so a stream's send buffer is framed where it wraps without a copy; a from plus length inside the array is the plain window. The Length field is always written, so another frame may follow; the Offset field only when it is not zero. Answers -1, writing nothing, for a length past the array, a stream ID that is not a varint, an end past 2^62 − 1, or no room.

const quicPutStream: (
  buf: u8[],
  at: i32,
  end: i32,
  streamId: i64,
  offset: i64,
  data: u8[],
  from: i32,
  length: i32,
  fin: boolean,
) => i32
bufu8[]required

The buffer to write into.

ati32required

The offset of the frame's first byte.

endi32required

One past the last byte the frame may use.

streamIdi64required

The stream the data belongs to.

offseti64required

The stream offset, in bytes, of the first byte carried.

datau8[]required

The bytes to carry, read as a ring; copied, not kept.

fromi32required

The index in data of the first byte to carry, inside the array when length is above zero.

lengthi32required

How many bytes to carry, at most data.length; 0 for a frame that only carries FIN.

finbooleanrequired

Whether these bytes end the stream, so that offset + length is its final size.

returnsi32

The offset past the frame, or -1 with nothing written.

quicPutStreamError

Writes a RESET_STREAM frame (§19.4) or, with finalSize at -1, a STOP_SENDING frame (§19.5). Answers -1 for a value no varint holds, or no room.

const quicPutStreamError: (
  buf: u8[],
  at: i32,
  end: i32,
  streamId: i64,
  errorCode: i64,
  finalSize: i64,
) => i32
bufu8[]required

The buffer to write into.

ati32required

The offset of the frame's first byte.

endi32required

One past the last byte the frame may use.

streamIdi64required

The stream being reset or asked to stop.

errorCodei64required

The application's error code for why.

finalSizei64required

For RESET_STREAM, the stream's final size: how many bytes of it were ever sent. -1 asks for STOP_SENDING instead.

returnsi32

The offset past the frame, or -1 with nothing written.

quicPutStreamValue

Writes a MAX_STREAM_DATA or STREAM_DATA_BLOCKED frame: the stream ID and the limit. Answers -1 for another type, a value no varint holds, or no room.

const quicPutStreamValue: (
  buf: u8[],
  at: i32,
  end: i32,
  type: i32,
  streamId: i64,
  value: i64,
) => i32
bufu8[]required

The buffer to write into.

ati32required

The offset of the frame's first byte.

endi32required

One past the last byte the frame may use.

typei32required

QUIC_FRAME_MAX_STREAM_DATA or QUIC_FRAME_STREAM_DATA_BLOCKED.

streamIdi64required

The stream the limit is for.

valuei64required

The stream's limit in bytes: the new one for MAX_STREAM_DATA, the one the sender is blocked at for STREAM_DATA_BLOCKED.

returnsi32

The offset past the frame, or -1 with nothing written.

quicPutTypeOnly

Writes a frame that is its type alone, PING or HANDSHAKE_DONE; -1 for another type or no room.

const quicPutTypeOnly: (
  buf: u8[],
  at: i32,
  end: i32,
  type: i32,
) => i32
bufu8[]required

The buffer to write into.

ati32required

The offset to write the one byte at.

endi32required

One past the last byte the frame may use, such as the end of the packet's room.

typei32required

QUIC_FRAME_PING or QUIC_FRAME_HANDSHAKE_DONE.

returnsi32

at + 1, or -1 with nothing written.

quicPutValue

Writes a frame of one varint after its type: MAX_DATA, MAX_STREAMS_BIDI, MAX_STREAMS_UNI, DATA_BLOCKED, STREAMS_BLOCKED_BIDI, STREAMS_BLOCKED_UNI or RETIRE_CONNECTION_ID. Answers -1 for another type, a value no varint holds, a stream count past 2^60, or no room.

const quicPutValue: (
  buf: u8[],
  at: i32,
  end: i32,
  type: i32,
  value: i64,
) => i32
bufu8[]required

The buffer to write into.

ati32required

The offset of the frame's first byte.

endi32required

One past the last byte the frame may use.

typei32required

One of the seven QUIC_FRAME_* types above.

valuei64required

What the type carries: a limit in bytes for MAX_DATA and DATA_BLOCKED, a count of streams for the four stream-count types, a sequence number for RETIRE_CONNECTION_ID.

returnsi32

The offset past the frame, or -1 with nothing written.

quicStreamOverhead

The bytes a STREAM frame's header takes for length bytes of data on streamId at offset: the type, the stream ID, the offset when it is not zero, and the length, which quicPutStream always writes.

const quicStreamOverhead: (
  streamId: i64,
  offset: i64,
  length: i32,
) => i32
streamIdi64required

The stream the frame is for; meaningful up to 2^62 − 1.

offseti64required

The stream offset, in bytes, of the frame's first data byte.

lengthi32required

How many data bytes the frame carries.

returnsi32

The header's size in bytes, not counting the data.

Classes

QuicFrame

One frame as quicParseFrame read it. Which fields mean something depends on type; the rest hold zero, or empty arrays.

  • ACK and ACK_ECN: largest, ackDelay (still scaled by the peer's exponent), the ranges as [smallest, largest] pairs from the highest down in ackRanges (ackRangeCount pairs stored, ackRangeTotal read), and for ACK_ECN the counts ect0, ect1 and ce.
  • CRYPTO: offset and the data dataStart, dataLength.
  • STREAM: streamId, offset, the data, and fin.
  • NEW_TOKEN and PATH_CHALLENGE / PATH_RESPONSE: the token or data.
  • RESET_STREAM: streamId, errorCode, the final size in value.
  • STOP_SENDING: streamId, errorCode.
  • MAX_DATA, MAX_STREAMS_, DATA_BLOCKED, STREAMS_BLOCKED_: value.
  • MAX_STREAM_DATA, STREAM_DATA_BLOCKED: streamId and value.
  • NEW_CONNECTION_ID: the sequence number in value, retirePriorTo, the ID's window connectionIdStart / connectionIdLength and the reset token's resetTokenStart (16 bytes) in the payload. RETIRE_CONNECTION_ID: value.
  • DATAGRAM: the payload as the data, and fin when the frame carried a Length (type 0x31).
  • CONNECTION_CLOSE: errorCode, frameType (0x1c only) and the reason phrase as the data.
class QuicFrame
Member
new QuicFrame() Makes an empty frame with room for QUIC_FRAME_MAX_ACK_RANGES ACK ranges, for quicParseFrame to fill.
ackDelay: i64 An ACK's delay as sent, not yet scaled by the peer's ack_delay_exponent.
ackRangeCount: i32 How many [smallest, largest] pairs of ackRanges hold an ACK range, at most QUIC_FRAME_MAX_ACK_RANGES.
ackRanges: i64[] An ACK's ranges as [smallest, largest] packet-number pairs, highest first. Only the first ackRangeCount pairs are meaningful; the array keeps its QUIC_FRAME_MAX_ACK_RANGES * 2 length.
ackRangeTotal: i64 How many ranges the ACK carried, which can exceed ackRangeCount when ranges past the stored cap were read and dropped.
ce: i64 An ACK_ECN's cumulative count of packets received marked ECN-CE (congestion experienced).
connectionIdLength: i32 A NEW_CONNECTION_ID's connection ID length in bytes, 1 to 20.
connectionIdStart: i32 Where a NEW_CONNECTION_ID's connection ID starts in the payload.
dataLength: i32 How many bytes of data start at dataStart.
dataStart: i32 Where the frame's data (stream or CRYPTO bytes, token, path data, datagram or reason phrase) starts in the payload.
ect0: i64 An ACK_ECN's cumulative count of packets received marked ECT(0).
ect1: i64 An ACK_ECN's cumulative count of packets received marked ECT(1).
end: i32 One past the frame's last byte, where the next frame starts.
errorCode: i64 The application or transport error code of a RESET_STREAM, STOP_SENDING or CONNECTION_CLOSE.
fin: boolean A STREAM frame's FIN bit (the stream ends with this data), or a DATAGRAM that carried a Length.
frameType: i64 The frame type a transport CONNECTION_CLOSE (0x1c) blames; 0 for the application form.
largest: i64 The largest packet number an ACK acknowledges.
offset: i64 The byte offset in the stream (STREAM) or the handshake stream (CRYPTO) where the data starts.
resetTokenStart: i32 Where a NEW_CONNECTION_ID's 16-byte stateless reset token starts in the payload.
retirePriorTo: i64 A NEW_CONNECTION_ID's Retire Prior To: every peer ID with a lower sequence number is to be retired.
streamId: i64 The stream a STREAM, RESET_STREAM, STOP_SENDING, MAX_STREAM_DATA or STREAM_DATA_BLOCKED frame names.
type: i32 The frame type, with every STREAM type answered as QUIC_FRAME_STREAM.
value: i64 The frame's one number: a limit, a final size or a sequence number, as the list above gives per type.

Limits

32

QUIC_FRAME_MAX_ACK_RANGES: i32

The most ACK ranges a QuicFrame keeps. A frame may list more, and every one is still checked; the ones past this are counted in ackRangeTotal but not stored. Loss recovery, which would read them, is WP34 Q3.

Constants

0x0f

QUIC_ERROR_AEAD_LIMIT_REACHED: i64

AEAD_LIMIT_REACHED: the keys reached their confidentiality or integrity limit (RFC 9001 §6.6).

0x0c

QUIC_ERROR_APPLICATION: i64

APPLICATION_ERROR: the application closed, reported in a transport close where 0x1d may not be sent.

0x09

QUIC_ERROR_CONNECTION_ID_LIMIT: i64

CONNECTION_ID_LIMIT_ERROR: the peer gave more connection IDs than active_connection_id_limit.

0x02

QUIC_ERROR_CONNECTION_REFUSED: i64

CONNECTION_REFUSED: the server will not accept the connection.

0x0100

QUIC_ERROR_CRYPTO: i64

CRYPTO_ERROR is this plus the TLS alert description (RFC 9001 §4.8): 0x0100 to 0x01ff.

0x0d

QUIC_ERROR_CRYPTO_BUFFER_EXCEEDED: i64

CRYPTO_BUFFER_EXCEEDED: the peer sent more CRYPTO data than the endpoint buffers.

0x06

QUIC_ERROR_FINAL_SIZE: i64

FINAL_SIZE_ERROR: a stream's final size changed, or data arrived past it.

0x03

QUIC_ERROR_FLOW_CONTROL: i64

FLOW_CONTROL_ERROR: the peer sent more data than the advertised limits allow.

0x07

QUIC_ERROR_FRAME_ENCODING: i64

FRAME_ENCODING_ERROR: a frame is badly formed, such as truncated or with a length past the packet.

0x01

QUIC_ERROR_INTERNAL: i64

INTERNAL_ERROR: the endpoint broke on its own, not because of anything the peer sent.

0x0b

QUIC_ERROR_INVALID_TOKEN: i64

INVALID_TOKEN: a server received a client Initial whose Token field it cannot accept, from a Retry or NEW_TOKEN.

0x0e

QUIC_ERROR_KEY_UPDATE: i64

KEY_UPDATE_ERROR: the peer made a mistake in a key update (RFC 9001 §6).

0x00

QUIC_ERROR_NO_ERROR: i64

NO_ERROR: the connection closes without an error; also quicParseFrame's answer for a good frame.

0x10

QUIC_ERROR_NO_VIABLE_PATH: i64

NO_VIABLE_PATH: no network path is fit for QUIC, such as one whose MTU is too small.

0x0a

QUIC_ERROR_PROTOCOL_VIOLATION: i64

PROTOCOL_VIOLATION: the peer broke the protocol in a way no more specific code names.

0x04

QUIC_ERROR_STREAM_LIMIT: i64

STREAM_LIMIT_ERROR: the peer opened a stream past the limit it was given.

0x05

QUIC_ERROR_STREAM_STATE: i64

STREAM_STATE_ERROR: a frame arrived for a stream not in a state that permits it.

0x08

QUIC_ERROR_TRANSPORT_PARAMETER: i64

TRANSPORT_PARAMETER_ERROR: the peer's transport parameters are malformed or invalid.

0x02

QUIC_FRAME_ACK: i32

ACK without ECN counts.

0x03

QUIC_FRAME_ACK_ECN: i32

ACK with the three ECN counts after the ranges.

0x1c

QUIC_FRAME_CONNECTION_CLOSE: i32

CONNECTION_CLOSE with a transport error code and the frame type that caused it.

0x1d

QUIC_FRAME_CONNECTION_CLOSE_APP: i32

CONNECTION_CLOSE with an application error code, allowed only in 1-RTT packets.

0x06

QUIC_FRAME_CRYPTO: i32

CRYPTO (§19.6): TLS handshake bytes at an offset in one packet number space's crypto stream.

0x30

QUIC_FRAME_DATAGRAM: i32

DATAGRAM (RFC 9221 §4): an unreliable application payload. Type 0x30 runs to the end of the packet and 0x31 carries a Length; quicParseFrame answers both as this type, with fin set for 0x31 (it had a Length).

0x31

QUIC_FRAME_DATAGRAM_LENGTH: i32

The DATAGRAM type with a Length field (RFC 9221 §4), which quicPutDatagram always writes.

0x14

QUIC_FRAME_DATA_BLOCKED: i32

DATA_BLOCKED (§19.12): the sender has data to send but the connection limit holds it back.

0x1e

QUIC_FRAME_HANDSHAKE_DONE: i32

HANDSHAKE_DONE (§19.20): the server confirms the handshake; only a server sends it.

0x10

QUIC_FRAME_MAX_DATA: i32

MAX_DATA (§19.9): the connection's flow-control limit, in bytes across every stream.

0x12

QUIC_FRAME_MAX_STREAMS_BIDI: i32

MAX_STREAMS (§19.11) for bidirectional streams: how many the peer may open in all.

0x13

QUIC_FRAME_MAX_STREAMS_UNI: i32

MAX_STREAMS (§19.11) for unidirectional streams: how many the peer may open in all.

0x11

QUIC_FRAME_MAX_STREAM_DATA: i32

MAX_STREAM_DATA (§19.10): one stream's flow-control limit, in bytes.

0x18

QUIC_FRAME_NEW_CONNECTION_ID: i32

NEW_CONNECTION_ID (§19.15): another connection ID the peer may use, with its reset token.

0x07

QUIC_FRAME_NEW_TOKEN: i32

NEW_TOKEN (§19.7): a server's token for the client to present in a later connection's Initial.

0x00

QUIC_FRAME_PADDING: i32

PADDING (§19.1): a single zero byte that means nothing, used to make a packet bigger.

0x1a

QUIC_FRAME_PATH_CHALLENGE: i32

PATH_CHALLENGE (§19.17): eight bytes the peer must echo in a PATH_RESPONSE to validate a path.

0x1b

QUIC_FRAME_PATH_RESPONSE: i32

PATH_RESPONSE (§19.18): the eight bytes of a PATH_CHALLENGE, echoed back.

0x01

QUIC_FRAME_PING: i32

PING (§19.2): the type alone, sent to get an acknowledgement or to keep a connection alive.

0x04

QUIC_FRAME_RESET_STREAM: i32

RESET_STREAM (§19.4): the sender abandons a stream, with an error code and the final size.

0x19

QUIC_FRAME_RETIRE_CONNECTION_ID: i32

RETIRE_CONNECTION_ID (§19.16): the sender stops using the peer's connection ID of a sequence number.

0x05

QUIC_FRAME_STOP_SENDING: i32

STOP_SENDING (§19.5): asks the peer to stop sending on a stream, with an error code.

0x08

QUIC_FRAME_STREAM: i32

The first of the eight STREAM types, 0x08 to 0x0f. quicParseFrame answers every one of them as this type, with the three low bits read into offset, dataLength and fin (§19.8).

0x16

QUIC_FRAME_STREAMS_BLOCKED_BIDI: i32

STREAMS_BLOCKED (§19.14) for bidirectional streams: the sender wants to open more than it may.

0x17

QUIC_FRAME_STREAMS_BLOCKED_UNI: i32

STREAMS_BLOCKED (§19.14) for unidirectional streams: the sender wants to open more than it may.

0x15

QUIC_FRAME_STREAM_DATA_BLOCKED: i32

STREAM_DATA_BLOCKED (§19.13): the sender is held back by one stream's limit.

8

QUIC_PATH_DATA_SIZE: i32

The length of a PATH_CHALLENGE's and a PATH_RESPONSE's data (RFC 9000 §19.17).

16

QUIC_RESET_TOKEN_SIZE: i32

The length of a stateless reset token (RFC 9000 §10.3).