# 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).

