velt/net/http/h2

API reference

HTTP/2's wire format (RFC 9113) and HPACK (RFC 7541), written in Velt: what the fetch client and HTTP/2 servers (the HTTP server package is one) share. It works on bytes (u8[] buffers and offsets) and leaves connections, streams and flow control to its users. For a walkthrough, read the guide.

import { errorName, FieldList } from "velt/net/http/h2";

Exports

errorNameThe name of error code code, for messages.frameLengthThe 24-bit payload length of the frame header at b[at..].isPrefaceWhether b[at..at + 24) is the client preface.mayBePrefaceWhether the bytes b[at..end) (fewer than 24) may still turn out to be the preface.readStreamIdThe 31-bit stream id at b[at..at + 4) (the reserved bit ignored).readU32The 32-bit number at b[at..at + 4).huffmanDecodeDecodes the Huffman-coded bytes src[start..end) into out from at: the end of what was written, or -1 for input that is not a valid code (EOS, or padding that is not up to 7 one bits).huffmanEncodeWrites the Huffman code of src[start..end) into out from at (room for huffmanLength bytes), padded with one bits: the end of what was written.huffmanLengthThe number of bytes the Huffman code of src[start..end) takes.FieldListDecoded header fields: bytes and ranges.FrameWriterAn output buffer of frames.HpackDecoderA header block's decoder for one connection.HpackEncoderA connection's response header encoder.ACKFlag: an acknowledgement (SETTINGS, PING).CANCELError code: the stream is no longer needed.COMPRESSION_ERRORError code: the HPACK state could not be kept.CONNECT_ERRORError code: a CONNECT tunnel failed.CONTINUATIONA CONTINUATION frame: the rest of a header block (§6.10).DATAA DATA frame: part of a stream's body (§6.1).DEFAULT_WINDOWThe default initial flow-control window (RFC 9113 §6.9.1).END_HEADERSFlag: the header block's last frame (HEADERS, CONTINUATION).END_STREAMFlag: the stream's last frame from this side (DATA, HEADERS).ENHANCE_YOUR_CALMError code: the peer generates too much load.FLOW_CONTROL_ERRORError code: the peer broke flow control.FRAME_SIZE_ERRORError code: a frame had the wrong size.GOAWAYA GOAWAY frame: the connection ends after the streams up to its last one (§6.8).HEADER_LENGTHThe frame header's length: 24-bit length, type, flags, 31-bit stream id.HEADERSA HEADERS frame: a header block, or its first part (§6.2).HTTP_1_1_REQUIREDError code: use HTTP/1.1 for this request.INADEQUATE_SECURITYError code: the TLS parameters are not good enough.INTERNAL_ERRORError code: the endpoint failed.MAX_MAX_FRAME_SIZEThe largest SETTINGS_MAX_FRAME_SIZE allowed.MAX_WINDOWThe largest a flow-control window may be.MIN_MAX_FRAME_SIZEThe default and smallest SETTINGS_MAX_FRAME_SIZE.NO_ERRORError code: none (a graceful end).PADDEDFlag: the payload is padded (DATA, HEADERS).PINGA PING frame, answered with its ACK (§6.7).PREFACE_LENGTHThe client connection preface (RFC 9113 §3.4): "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n".PRIORITYA PRIORITY frame, deprecated and ignored (§6.3).PRIORITY_FLAGFlag: HEADERS carries priority fields (deprecated, skipped).PROTOCOL_ERRORError code: the peer broke the protocol.PUSH_PROMISEA PUSH_PROMISE frame (server push, which this implementation turns off) (§6.6).REFUSED_STREAMError code: the stream was refused before any processing (safe to retry).RST_STREAMAn RST_STREAM frame: ends one stream at once (§6.4).SETTINGSA SETTINGS frame: the sender's settings, or the acknowledgement of the peer's (§6.5).SETTINGS_ENABLE_CONNECT_PROTOCOLRFC 8441: extended CONNECT (WebSockets over HTTP/2).SETTINGS_ENABLE_PUSHSetting: whether server push is allowed (0 or 1).SETTINGS_HEADER_TABLE_SIZESetting: the largest HPACK dynamic table the sender's decoder allows.SETTINGS_INITIAL_WINDOW_SIZESetting: a new stream's flow-control window.SETTINGS_MAX_CONCURRENT_STREAMSSetting: the most streams the peer may have open at once.SETTINGS_MAX_FRAME_SIZESetting: the largest frame payload the sender accepts.SETTINGS_MAX_HEADER_LIST_SIZESetting: the largest header list the sender accepts (advisory).SETTINGS_TIMEOUTError code: SETTINGS were not acknowledged in time.STREAM_CLOSEDError code: a frame came for a half-closed stream.WINDOW_UPDATEA WINDOW_UPDATE frame: more of a flow-control window (§6.9).

function

errorName

#std/net/http/h2/frame.vlt:141

Re-exported from velt/net/http/h2/frame

function errorName(code: i64): string

The name of error code code, for messages.

function

frameLength

#std/net/http/h2/frame.vlt:120

Re-exported from velt/net/http/h2/frame

function frameLength(b: u8[], at: i64): i64

The 24-bit payload length of the frame header at b[at..].

function

isPreface

#std/net/http/h2/frame.vlt:8

Re-exported from velt/net/http/h2/frame

function isPreface(b: u8[], at: i64): bool

Whether b[at..at + 24) is the client preface.

function

mayBePreface

#std/net/http/h2/frame.vlt:13

Re-exported from velt/net/http/h2/frame

function mayBePreface(b: u8[], at: i64, end: i64): bool

Whether the bytes b[at..end) (fewer than 24) may still turn out to be the preface.

function

readStreamId

#std/net/http/h2/frame.vlt:125

Re-exported from velt/net/http/h2/frame

function readStreamId(b: u8[], at: i64): i64

The 31-bit stream id at b[at..at + 4) (the reserved bit ignored).

function

readU32

#std/net/http/h2/frame.vlt:133

Re-exported from velt/net/http/h2/frame

function readU32(b: u8[], at: i64): i64

The 32-bit number at b[at..at + 4).

function

huffmanDecode

#std/net/http/h2/huffman.vlt:24

Re-exported from velt/net/http/h2/huffman

function huffmanDecode(
  src: u8[],
  start: i64,
  end: i64,
  out: u8[],
  at: i64,
): i64

Decodes the Huffman-coded bytes src[start..end) into out from at: the end of what was written, or -1 for input that is not a valid code (EOS, or padding that is not up to 7 one bits). out must have room for (end - start) * 8 / 5 bytes (the shortest code is 5 bits).

function

huffmanEncode

#std/net/http/h2/huffman.vlt:95

Re-exported from velt/net/http/h2/huffman

function huffmanEncode(
  src: u8[],
  start: i64,
  end: i64,
  out: u8[],
  at: i64,
): i64

Writes the Huffman code of src[start..end) into out from at (room for huffmanLength bytes), padded with one bits: the end of what was written.

function

huffmanLength

#std/net/http/h2/huffman.vlt:83

Re-exported from velt/net/http/h2/huffman

function huffmanLength(src: u8[], start: i64, end: i64): i64

The number of bytes the Huffman code of src[start..end) takes.

class

FieldList

#std/net/http/h2/field_list.vlt:7

Re-exported from velt/net/http/h2/field_list

Decoded header fields: bytes and ranges.

Parameter ofHpackDecoder.decode

buf: u8[] = Buffer.alloc(512)No doc comment yet

length: i64 = 0

The bytes of buf in use.

heads: i64[] = []

Four offsets per field.

size: i64 = 0

The list's size as SETTINGS_MAX_HEADER_LIST_SIZE counts it (each field + 32).

overflow: bool = false

A field did not fit within the limit: the later ones were decoded but not kept.

clear()

Empties the list for the next block.

get count(): i64

The number of fields.

reserve(n: i64)

Room for n more bytes.

text(s: string)

Appends the bytes of s.

bytes(b: u8[])

Appends b.

name(i: i64): string

Field i's name as text.

value(i: i64): string

Field i's value as text.

nameIs(i: i64, s: string): bool

Whether field i's name is s (lowercase, as HTTP/2 sends names).

nameLength(i: i64): i64

The length of field i's name.

nameByte(i: i64): u8

The first byte of field i's name.

pairs(): [string, string][]

Field i as name: value pairs, for tests and errors.

class

FrameWriter

#std/net/http/h2/frame_writer.vlt:19

Re-exported from velt/net/http/h2/frame_writer

An output buffer of frames.

Parameter ofHpackEncoder.begin

buf: u8[] = Buffer.alloc(16384)No doc comment yet

length: i64 = 0No doc comment yet

reserve(n: i64)

Room for n more bytes.

header(length: i64, type: i64, flags: i64, stream: i64)

A frame header (room for it is the caller's: reserve).

u32(v: i64)

A 32-bit number (room for it is the caller's).

byte(v: i64)

One byte (room for it is the caller's).

settings(pairs: i64[])

A SETTINGS frame with pairs (identifier, value, ...).

settingsAck()

A SETTINGS acknowledgement.

pingAck(src: u8[], at: i64)

A PING acknowledgement echoing src[at..at + 8).

goaway(lastStream: i64, code: i64, debug: string)

A GOAWAY frame: the last stream processed, the error code and a debug text.

rstStream(stream: i64, code: i64)

RST_STREAM for stream with error code.

windowUpdate(stream: i64, increment: i64)

WINDOW_UPDATE of stream (0: the connection) by increment.

data(stream: i64, flags: i64, src: u8[], start: i64, end: i64)

A DATA frame of stream carrying src[start..end).

beginHeaders(): i64

Starts a HEADERS frame of stream: its header is filled in by endHeaders, once the block (written after it) is known. Returns where the frame starts.

endHeaders(at: i64, stream: i64, flags: i64, maxFrame: i64)

Ends the HEADERS frame begun at at (flags besides END_HEADERS: END_STREAM or none): a block larger than maxFrame is split into HEADERS and CONTINUATION frames, which leave together (RFC 9113 §4.3).

class

HpackDecoder

#std/net/http/h2/hpack_decoder.vlt:21

Re-exported from velt/net/http/h2/hpack_decoder

A header block's decoder for one connection.

table: DynamicTable

The dynamic table (public for tests).

maxListSize: i64

The most a block's fields may add up to (SETTINGS_MAX_HEADER_LIST_SIZE).

constructor(tableSize: i64 = 4096, maxListSize: i64 = 16384)No doc comment yet

decode(src: u8[], start: i64, end: i64, out: FieldList): bool

Decodes the block src[start..end) into out (appended): false when it is not valid HPACK (a COMPRESSION_ERROR, which ends the connection). Fields beyond maxListSize set out.overflow and are not kept.

class

HpackEncoder

#std/net/http/h2/hpack_encoder.vlt:20

Re-exported from velt/net/http/h2/hpack_encoder

A connection's response header encoder.

setMaxSize(size: i64)

The peer's decoder allows size bytes of table (SETTINGS_HEADER_TABLE_SIZE): the encoder uses at most 4096 of them, and announces a reduction with its next block.

begin(out: FrameWriter)

Starts a block: a pending table size update goes first (RFC 7541 §4.2).

status(out: FrameWriter, code: i64)

:status code.

request(out: FrameWriter, method: string, scheme: string, authority: string, path: string)

A request's pseudo-headers (the client side): the static table's entries where they match (GET, POST, /, http, https), else literals by static name.

contentLength(out: FrameWriter, n: i64)

content-length: n, without indexing (static name 28).

field(out: FrameWriter, name: string, value: string)

Field name: value (name in lowercase).

const

ACK

#std/net/http/h2/frame.vlt:54

Re-exported from velt/net/http/h2/frame

const ACK: i64 = 0x1

Flag: an acknowledgement (SETTINGS, PING).

const

CANCEL

#std/net/http/h2/frame.vlt:98

Re-exported from velt/net/http/h2/frame

const CANCEL: i64 = 8

Error code: the stream is no longer needed.

const

COMPRESSION_ERROR

#std/net/http/h2/frame.vlt:100

Re-exported from velt/net/http/h2/frame

const COMPRESSION_ERROR: i64 = 9

Error code: the HPACK state could not be kept.

const

CONNECT_ERROR

#std/net/http/h2/frame.vlt:102

Re-exported from velt/net/http/h2/frame

const CONNECT_ERROR: i64 = 10

Error code: a CONNECT tunnel failed.

const

CONTINUATION

#std/net/http/h2/frame.vlt:47

Re-exported from velt/net/http/h2/frame

const CONTINUATION: i64 = 9

A CONTINUATION frame: the rest of a header block (§6.10).

const

DATA

#std/net/http/h2/frame.vlt:29

Re-exported from velt/net/http/h2/frame

const DATA: i64 = 0

A DATA frame: part of a stream's body (§6.1).

const

DEFAULT_WINDOW

#std/net/http/h2/frame.vlt:115

Re-exported from velt/net/http/h2/frame

const DEFAULT_WINDOW: i64 = 65535

The default initial flow-control window (RFC 9113 §6.9.1).

const

END_HEADERS

#std/net/http/h2/frame.vlt:56

Re-exported from velt/net/http/h2/frame

const END_HEADERS: i64 = 0x4

Flag: the header block's last frame (HEADERS, CONTINUATION).

const

END_STREAM

#std/net/http/h2/frame.vlt:52

Re-exported from velt/net/http/h2/frame

const END_STREAM: i64 = 0x1

Flag: the stream's last frame from this side (DATA, HEADERS).

const

ENHANCE_YOUR_CALM

#std/net/http/h2/frame.vlt:104

Re-exported from velt/net/http/h2/frame

const ENHANCE_YOUR_CALM: i64 = 11

Error code: the peer generates too much load.

const

FLOW_CONTROL_ERROR

#std/net/http/h2/frame.vlt:88

Re-exported from velt/net/http/h2/frame

const FLOW_CONTROL_ERROR: i64 = 3

Error code: the peer broke flow control.

const

FRAME_SIZE_ERROR

#std/net/http/h2/frame.vlt:94

Re-exported from velt/net/http/h2/frame

const FRAME_SIZE_ERROR: i64 = 6

Error code: a frame had the wrong size.

const

GOAWAY

#std/net/http/h2/frame.vlt:43

Re-exported from velt/net/http/h2/frame

const GOAWAY: i64 = 7

A GOAWAY frame: the connection ends after the streams up to its last one (§6.8).

const

HEADER_LENGTH

#std/net/http/h2/frame.vlt:24

Re-exported from velt/net/http/h2/frame

const HEADER_LENGTH: i64 = 9

The frame header's length: 24-bit length, type, flags, 31-bit stream id.

const

HEADERS

#std/net/http/h2/frame.vlt:31

Re-exported from velt/net/http/h2/frame

const HEADERS: i64 = 1

A HEADERS frame: a header block, or its first part (§6.2).

const

HTTP_1_1_REQUIRED

#std/net/http/h2/frame.vlt:108

Re-exported from velt/net/http/h2/frame

const HTTP_1_1_REQUIRED: i64 = 13

Error code: use HTTP/1.1 for this request.

const

INADEQUATE_SECURITY

#std/net/http/h2/frame.vlt:106

Re-exported from velt/net/http/h2/frame

const INADEQUATE_SECURITY: i64 = 12

Error code: the TLS parameters are not good enough.

const

INTERNAL_ERROR

#std/net/http/h2/frame.vlt:86

Re-exported from velt/net/http/h2/frame

const INTERNAL_ERROR: i64 = 2

Error code: the endpoint failed.

const

MAX_MAX_FRAME_SIZE

#std/net/http/h2/frame.vlt:113

Re-exported from velt/net/http/h2/frame

const MAX_MAX_FRAME_SIZE: i64 = 16777215

The largest SETTINGS_MAX_FRAME_SIZE allowed.

const

MAX_WINDOW

#std/net/http/h2/frame.vlt:117

Re-exported from velt/net/http/h2/frame

const MAX_WINDOW: i64 = 0x7fffffff

The largest a flow-control window may be.

const

MIN_MAX_FRAME_SIZE

#std/net/http/h2/frame.vlt:111

Re-exported from velt/net/http/h2/frame

const MIN_MAX_FRAME_SIZE: i64 = 16384

The default and smallest SETTINGS_MAX_FRAME_SIZE.

const

NO_ERROR

#std/net/http/h2/frame.vlt:82

Re-exported from velt/net/http/h2/frame

const NO_ERROR: i64 = 0

Error code: none (a graceful end).

const

PADDED

#std/net/http/h2/frame.vlt:58

Re-exported from velt/net/http/h2/frame

const PADDED: i64 = 0x8

Flag: the payload is padded (DATA, HEADERS).

const

PING

#std/net/http/h2/frame.vlt:41

Re-exported from velt/net/http/h2/frame

const PING: i64 = 6

A PING frame, answered with its ACK (§6.7).

const

PREFACE_LENGTH

#std/net/http/h2/frame.vlt:5

Re-exported from velt/net/http/h2/frame

const PREFACE_LENGTH: i64 = 24

The client connection preface (RFC 9113 §3.4): "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n".

const

PRIORITY

#std/net/http/h2/frame.vlt:33

Re-exported from velt/net/http/h2/frame

const PRIORITY: i64 = 2

A PRIORITY frame, deprecated and ignored (§6.3).

const

PRIORITY_FLAG

#std/net/http/h2/frame.vlt:60

Re-exported from velt/net/http/h2/frame

const PRIORITY_FLAG: i64 = 0x20

Flag: HEADERS carries priority fields (deprecated, skipped).

const

PROTOCOL_ERROR

#std/net/http/h2/frame.vlt:84

Re-exported from velt/net/http/h2/frame

const PROTOCOL_ERROR: i64 = 1

Error code: the peer broke the protocol.

const

PUSH_PROMISE

#std/net/http/h2/frame.vlt:39

Re-exported from velt/net/http/h2/frame

const PUSH_PROMISE: i64 = 5

A PUSH_PROMISE frame (server push, which this implementation turns off) (§6.6).

const

REFUSED_STREAM

#std/net/http/h2/frame.vlt:96

Re-exported from velt/net/http/h2/frame

const REFUSED_STREAM: i64 = 7

Error code: the stream was refused before any processing (safe to retry).

const

RST_STREAM

#std/net/http/h2/frame.vlt:35

Re-exported from velt/net/http/h2/frame

const RST_STREAM: i64 = 3

An RST_STREAM frame: ends one stream at once (§6.4).

const

SETTINGS

#std/net/http/h2/frame.vlt:37

Re-exported from velt/net/http/h2/frame

const SETTINGS: i64 = 4

A SETTINGS frame: the sender's settings, or the acknowledgement of the peer's (§6.5).

const

SETTINGS_ENABLE_CONNECT_PROTOCOL

#std/net/http/h2/frame.vlt:77

Re-exported from velt/net/http/h2/frame

const SETTINGS_ENABLE_CONNECT_PROTOCOL: i64 = 8

RFC 8441: extended CONNECT (WebSockets over HTTP/2).

const

SETTINGS_ENABLE_PUSH

#std/net/http/h2/frame.vlt:67

Re-exported from velt/net/http/h2/frame

const SETTINGS_ENABLE_PUSH: i64 = 2

Setting: whether server push is allowed (0 or 1).

const

SETTINGS_HEADER_TABLE_SIZE

#std/net/http/h2/frame.vlt:65

Re-exported from velt/net/http/h2/frame

const SETTINGS_HEADER_TABLE_SIZE: i64 = 1

Setting: the largest HPACK dynamic table the sender's decoder allows.

const

SETTINGS_INITIAL_WINDOW_SIZE

#std/net/http/h2/frame.vlt:71

Re-exported from velt/net/http/h2/frame

const SETTINGS_INITIAL_WINDOW_SIZE: i64 = 4

Setting: a new stream's flow-control window.

const

SETTINGS_MAX_CONCURRENT_STREAMS

#std/net/http/h2/frame.vlt:69

Re-exported from velt/net/http/h2/frame

const SETTINGS_MAX_CONCURRENT_STREAMS: i64 = 3

Setting: the most streams the peer may have open at once.

const

SETTINGS_MAX_FRAME_SIZE

#std/net/http/h2/frame.vlt:73

Re-exported from velt/net/http/h2/frame

const SETTINGS_MAX_FRAME_SIZE: i64 = 5

Setting: the largest frame payload the sender accepts.

const

SETTINGS_MAX_HEADER_LIST_SIZE

#std/net/http/h2/frame.vlt:75

Re-exported from velt/net/http/h2/frame

const SETTINGS_MAX_HEADER_LIST_SIZE: i64 = 6

Setting: the largest header list the sender accepts (advisory).

const

SETTINGS_TIMEOUT

#std/net/http/h2/frame.vlt:90

Re-exported from velt/net/http/h2/frame

const SETTINGS_TIMEOUT: i64 = 4

Error code: SETTINGS were not acknowledged in time.

const

STREAM_CLOSED

#std/net/http/h2/frame.vlt:92

Re-exported from velt/net/http/h2/frame

const STREAM_CLOSED: i64 = 5

Error code: a frame came for a half-closed stream.

const

WINDOW_UPDATE

#std/net/http/h2/frame.vlt:45

Re-exported from velt/net/http/h2/frame

const WINDOW_UPDATE: i64 = 8

A WINDOW_UPDATE frame: more of a flow-control window (§6.9).