# gizlang/recovery

what a sender knows of the path to its peer. The round-trip time (RFC 9002 5), when a packet counts as lost (RFC 9002 6.1), the probe timeout (6.2), and how many bytes may be in flight and how fast they may leave (congestion control, RFC 9002 7, with NewReno's window). The state is plain numbers in microseconds and bytes, so any transport can keep it: gizlang/quic keeps one per connection.

```gizlang
import * as Recovery from "gizlang/recovery";
```

## Types

### `Path`

```gizlang
type Path = { latest: i64; smoothed: i64; variation: i64; least: i64; window: i64; threshold: i64; inFlight: i64; recoveryStart: i64; datagram: i64; credit: i64; }
```

The path as the sender sees it. Times are microseconds, sizes bytes.

- `latest`: `i64` — The latest round-trip sample, the smoothed estimate, its variation and the least seen; 0 before a sample.
- `smoothed`: `i64`
- `variation`: `i64`
- `least`: `i64`
- `window`: `i64` — The congestion window, the slow-start threshold and the bytes in flight.
- `threshold`: `i64`
- `inFlight`: `i64`
- `recoveryStart`: `i64` — When the current recovery period began (0: none): a loss of a packet sent before it does not shrink the window
again (RFC 9002 7.3.2).
- `datagram`: `i64` — The largest datagram, and the bytes acknowledged toward the next datagram of window in congestion avoidance.
- `credit`: `i64`

## Functions

### `newPath`

```gizlang
function newPath(datagram: i64): Path
```

The path of a new connection whose datagrams are at most DATAGRAM bytes (RFC 9002 7.2).

Effects: fail.

## Methods

### `Path.sample`

```gizlang
function Path.sample(self: mut Path, rtt: i64, delay: i64, mostDelay: i64, confirmed: bool): void
```

A round-trip sample of RTT microseconds, of which the peer held the acknowledgement DELAY (RFC 9002 5.3). Before the
handshake is confirmed the delay is not capped by the peer's MOST_DELAY.

Effects: fail.

### `Path.rtt`

```gizlang
function Path.rtt(self: Path): i64
```

The smoothed round-trip time, or INITIAL_RTT before a sample.

### `Path.probeTimeout`

```gizlang
function Path.probeTimeout(self: Path, mostDelay: i64): i64
```

The probe timeout without backoff (RFC 9002 6.2.1): the peer may hold an acknowledgement MOST_DELAY.

Effects: fail.

### `Path.lossDelay`

```gizlang
function Path.lossDelay(self: Path): i64
```

How long after a later packet was acknowledged an earlier one counts as lost (RFC 9002 6.1.2).

Effects: fail.

### `Path.room`

```gizlang
function Path.room(self: Path): i64
```

The bytes that may still go into flight now.

Effects: fail.

### `Path.rate`

```gizlang
function Path.rate(self: Path): i64
```

Bytes a second at which to space what is sent: a window each round trip, with a quarter to spare (RFC 9002 7.7).

Effects: fail.

### `Path.sent`

```gizlang
function Path.sent(self: mut Path, bytes: i64): void
```

BYTES went into flight.

Effects: fail.

### `Path.acked`

```gizlang
function Path.acked(self: mut Path, bytes: i64, sent: i64): void
```

BYTES sent at SENT were acknowledged: they leave flight and grow the window, unless they were sent before the
current recovery period began (RFC 9002 7.3).

Effects: fail.

### `Path.lost`

```gizlang
function Path.lost(self: mut Path, bytes: i64, sent: i64, now: i64): void
```

BYTES sent at SENT were lost, found at NOW: they leave flight, and the first loss after the recovery period began
halves the window (RFC 9002 7.3.2).

Effects: fail.

### `Path.discarded`

```gizlang
function Path.discarded(self: mut Path, bytes: i64): void
```

BYTES leave flight without a signal: their keys were discarded (RFC 9002 6.4).

Effects: fail.

### `Path.collapse`

```gizlang
function Path.collapse(self: mut Path): void
```

Every packet over a period longer than the persistent congestion duration was lost (RFC 9002 7.6): the window
starts again from its least.

Effects: fail.

## Constants

### `INITIAL_RTT`

```gizlang
const INITIAL_RTT = 333000
```

The round-trip time before a sample (RFC 9002 6.2.2), and the timer granularity (6.1.2), in microseconds.

### `GRANULARITY`

```gizlang
const GRANULARITY = 1000
```

The timer granularity (RFC 9002 6.1.2), in microseconds.

### `PACKET_THRESHOLD`

```gizlang
const PACKET_THRESHOLD = 3
```

A packet this many below the largest acknowledged is lost (RFC 9002 6.1.1).

