GizStack
View .mdOpen in ChatGPTOpen in Claude

gizlang/quic

QUIC version 1 (RFC 9000) on a UDP socket. Packets are protected with the keys of a TLS 1.3 handshake (RFC 9001, the engines of gizlang/tls in QUIC mode), and losses and the congestion window follow RFC 9002 (gizlang/recovery). An Endpoint owns one socket and its connections: one task reads datagrams, one runs the timers. A connection's state is one value in a Ref. Each step takes it, changes it and stores it back without waiting in between, then sends the datagrams the step queued; tasks never see a state half changed. A step that the network moved stores the endpoint's progress Cell, which wakes the tasks that wait for a stream, a connection or credit.

gizlang
import * as Quic from "gizlang/quic";

Types

Var

gizlang
type Var = { value: i64; next: i64; }

A variable-length integer at AT: its value (-1 when DATA ends first) and the index after it.

  • value: i64
  • next: i64

Endpoint

gizlang
type Endpoint

A UDP socket and its connections: a server's (listen) or one client's (connect).

Opaque: create and use it through this module's functions.

Connection

gizlang
type Connection

A QUIC connection.

Opaque: create and use it through this module's functions.

Stream

gizlang
type Stream

A stream of a connection (RFC 9000 2).

  • id: i64

StreamError

gizlang
type StreamError = { code: i64; }

Why a stream ended early: the application code of the peer's reset, or the error that ended the connection.

  • code: i64

Functions

putVar

gizlang
function putVar(out: mut bytes, v: i64): void

Appends V as a variable-length integer (RFC 9000 16), in the fewest bytes.

Effects: fail, alloc.

takeVar

gizlang
function takeVar(data: bytes, at: i64): Var

The variable-length integer at AT in DATA (RFC 9000 16).

Effects: fail.

initialSecrets

gizlang
function initialSecrets(id: bytes): Vec<bytes>

The Initial keys of each side, from the client's first Destination Connection ID (RFC 9001 5.2).

Effects: fail, read, write, console, io, alloc.

listen

gizlang
function listen(credentials: Tls.Credentials, host: string, port: i64, protocols: Vec<string>): Endpoint throws IoError

A server on UDP HOST:PORT ("" for every address, port 0 for any) with the certificates of CREDENTIALS, speaking one of PROTOCOLS (ALPN names).

Effects: fail, read, write, console, io, alloc.

connect

gizlang
function connect(host: string, port: i64, name: string, roots: Vec<Crypto.Certificate>, protocols: Vec<string>): Connection throws IoError

A connection to HOST:PORT whose certificate names NAME and comes from one of ROOTS, speaking one of PROTOCOLS; it returns once the handshake is done.

Effects: fail, read, write, console, io, alloc.

Methods

Endpoint.port

gizlang
function Endpoint.port(self: Endpoint): i64

The UDP port of the endpoint.

Effects: fail, io, alloc.

Endpoint.accept

gizlang
function Endpoint.accept(self: Endpoint): Option<Connection>

The next connection whose handshake is done; none once the endpoint closed.

Effects: fail, read, write, io, alloc.

Endpoint.close

gizlang
function Endpoint.close(self: Endpoint, code: i64): void

Closes every connection with the application's CODE, then the socket.

Effects: fail, read, write, io, alloc.

Connection.alive

gizlang
function Connection.alive(self: Connection): bool

Whether the connection still runs.

Effects: fail, read.

Connection.protocol

gizlang
function Connection.protocol(self: Connection): string

The ALPN protocol the peers chose.

Effects: fail, read.

Connection.error

gizlang
function Connection.error(self: Connection): i64

The error code that ended the connection, -1 while it runs.

Effects: fail, read.

Connection.acceptStream

gizlang
function Connection.acceptStream(self: Connection): Option<Stream>

The next stream the peer opened; none once the connection ended.

Effects: fail, read, write, io, alloc.

Connection.open

gizlang
function Connection.open(self: Connection, uni: bool): Option<Stream>

Opens a stream of this side: both ways, or only out when UNI; it waits for the peer's credit. None once the connection ended.

Effects: fail, read, write, io, alloc.

Connection.close

gizlang
function Connection.close(self: Connection, code: i64): void

Closes the connection with the application's CODE (RFC 9000 10.2). A client's endpoint closes with it.

Effects: fail, read, write, io, alloc.

Stream.bidirectional

gizlang
function Stream.bidirectional(self: Stream): bool

Whether the stream goes both ways.

Effects: fail.

Stream.read

gizlang
function Stream.read(self: Stream): bytes throws StreamError

The next bytes the peer sent, waiting for them; empty at the stream's end. It throws when the peer reset the stream or the connection ended first.

Effects: fail, read, write, io, alloc.

Stream.write

gizlang
function Stream.write(self: Stream, data: bytes, last: bool): void throws StreamError

Sends DATA, and the end of the stream after it when LAST; it waits while much is still unsent. It throws when the stream can no longer send: the peer asked it to stop, it ended, or the connection ended.

Effects: fail, read, write, io, alloc.

Stream.reset

gizlang
function Stream.reset(self: Stream, code: i64): void

Abandons sending with the application's CODE (RESET_STREAM).

Effects: fail, read, write, io, alloc.

Stream.stop

gizlang
function Stream.stop(self: Stream, code: i64): void

Asks the peer to stop sending, with the application's CODE (STOP_SENDING); what arrives is dropped.

Effects: fail, read, write, io, alloc.

Constants

NO_ERROR

gizlang
const NO_ERROR: i64 = 0

Transport error codes (RFC 9000 20.1).

INTERNAL_ERROR

gizlang
const INTERNAL_ERROR: i64 = 1

The transport error INTERNAL_ERROR (RFC 9000 20.1).

FLOW_CONTROL_ERROR

gizlang
const FLOW_CONTROL_ERROR: i64 = 3

The transport error FLOW_CONTROL_ERROR (RFC 9000 20.1).

STREAM_LIMIT_ERROR

gizlang
const STREAM_LIMIT_ERROR: i64 = 4

The transport error STREAM_LIMIT_ERROR (RFC 9000 20.1).

STREAM_STATE_ERROR

gizlang
const STREAM_STATE_ERROR: i64 = 5

The transport error STREAM_STATE_ERROR (RFC 9000 20.1).

FINAL_SIZE_ERROR

gizlang
const FINAL_SIZE_ERROR: i64 = 6

The transport error FINAL_SIZE_ERROR (RFC 9000 20.1).

FRAME_ENCODING_ERROR

gizlang
const FRAME_ENCODING_ERROR: i64 = 7

The transport error FRAME_ENCODING_ERROR (RFC 9000 20.1).

TRANSPORT_PARAMETER_ERROR

gizlang
const TRANSPORT_PARAMETER_ERROR: i64 = 8

The transport error TRANSPORT_PARAMETER_ERROR (RFC 9000 20.1).

PROTOCOL_VIOLATION

gizlang
const PROTOCOL_VIOLATION: i64 = 10

The transport error PROTOCOL_VIOLATION (RFC 9000 20.1).

APPLICATION_ERROR

gizlang
const APPLICATION_ERROR: i64 = 12

The transport error APPLICATION_ERROR (RFC 9000 20.1).

CRYPTO_BUFFER_EXCEEDED

gizlang
const CRYPTO_BUFFER_EXCEEDED: i64 = 13

The transport error CRYPTO_BUFFER_EXCEEDED (RFC 9000 20.1).

CRYPTO_ERROR

gizlang
const CRYPTO_ERROR: i64 = 256

A TLS alert ends the connection with this plus the alert (RFC 9001 4.8).