Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
d040086
chore(quest): claim quest/m0/nightly/credential-established.md
kixelated Nov 18, 2026
cc336d2
feat(net): a reconnecting client is established by the peer accepting…
kixelated Nov 18, 2026
392cdb6
feat(js/net): Reload is established by the peer accepting its credential
kixelated Nov 18, 2026
c01962c
docs: a session is established once the peer accepts its credential
kixelated Nov 18, 2026
6aebca0
chore: format, and name acceptance in the coverage table
kixelated Nov 18, 2026
10a12e8
test(ffi): the first-dial state test no longer assumes a refusal
kixelated Nov 18, 2026
fa9fe36
quest: rewrite credential-established to the binding tests it leaves
kixelated Nov 18, 2026
59eca35
feat(tokio): a connection reports Connected once its peer accepts the…
kixelated Nov 18, 2026
3f6a5d7
test: binding reconnect tests drop a session once it reports connected
kixelated Nov 18, 2026
9d7c4fd
feat(net): Reload reports connected once the peer accepts the session
kixelated Nov 18, 2026
e91df33
fix(net): a predecessor's retirement mid-dial stays offline until the…
kixelated Nov 18, 2026
91a60fb
quest: finish credential-established
kixelated Nov 18, 2026
d70adc3
feat(tokio): established resolves once any session was, and relay dra…
kixelated Nov 18, 2026
8bd9944
test(interop): a refused WebSocket session never reads as connected
kixelated Nov 18, 2026
00d4cb1
fix(net): Action::Established carries its session, which an early GOA…
kixelated Nov 18, 2026
50a604c
fix(net): box the established session, which clippy flags as a large …
kixelated Nov 18, 2026
1d2ab40
style: rustfmt
kixelated Nov 18, 2026
51e8538
feat(net)!: on a version that answers the credential, uptime never es…
kixelated Nov 18, 2026
2bf3599
docs(verify-reconnect): sync the model to the uptime rule
kixelated Nov 18, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 7 additions & 6 deletions .claude/skills/verify-reconnect/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,11 @@ Each rule is an INVARIANT; the harm says why it matters. All but `NoOrphan`, `Re
| --- | --- | --- |
| `NoStaleSession` | The session a `Connection` reports as live is never one the policy aborted or started closing. | An app opens subscriptions on a session that is going away. |
| `StatusTruthful` | Connected is on the policy's live session, Migrating on its predecessor while nothing else is live, Closed exactly when the policy is done, and the predecessor `Connection::close` drains is the policy's. | Status or `close` acts on the wrong session, or a closed loop looks alive. |
| `ConnectedMeansEstablished` | A `Connection` reports a session only once the policy reported it established (`Action::Established`): its peer accepted the credential or drained it with a GOAWAY, or, on a version that never answers the credential (moq-lite 03/04), it stayed up past the healthy bar. Uptime alone never establishes a session on a version that answers. | A refused session reads as connected, and `established()` returns `Ok` for it, or a lite-07 session the peer never accepted reads as connected once it is a second old. |
| `OfflineMeansNothingServes` | Disconnected is reported only when no predecessor still serves (`Action::Offline`: "nothing serves anymore"); one closing gracefully carries nothing and takes no new work. | An app waiting on `established` stalls, and the UI says disconnected, while a session still carries its media. |
| `NoOrphan` | Until the policy is done, every open session is the live one or the predecessor. | A transport and the peer's state stay open with nothing able to reach them. |
| `PresenceBalanced` | `sessions_started - sessions_ended` is 1 while connected and 0 otherwise. | Presence counts drift on every migration. |
| `FirstWalkFailsFast` | Until a session has stayed up past the healthy bar or got a GOAWAY, which no refusal sends, no failed dial or closed session backs off: either ends the policy. | A setup mistake (an untrusted certificate, no version in common) or a refused credential retries forever instead of surfacing. |
| `FirstWalkFailsFast` | Until a session was reported established (see `ConnectedMeansEstablished`; a GOAWAY counts, since no refusal sends one), no failed dial or closed session backs off: either ends the policy. Only a session reported established establishes the policy. | A setup mistake (an untrusted certificate, no version in common) or a refused credential retries forever instead of surfacing. |
| `RedirectFollowed` | A dial never goes elsewhere than a redirect, named to a session the policy still holds, that the policy never acted on. | The replacement lands back on the node that is leaving. |

## Run
Expand All @@ -28,7 +29,7 @@ quest gate just rs tla moq-net/verify/reconnect/Handover.tla
quest gate just rs tla moq-net/verify/reconnect/Handover.tla -config rs/moq-net/verify/reconnect/RestartHandoff.cfg
```

The first checks every rule over four sessions: about 1.5M distinct states, under a minute. The second checks the same rules under `Restart::Handoff` over three sessions: about 330k states. All pass at the sync commit. Nightly runs every config here and fails if a config with an `\* Open finding:` line passes. The `VIEW` counts states that differ only in what nothing reads again as one: a closed session's details unless it is still the live one, a deadline of a phase the policy left, and where no dial is headed.
The first checks every rule over four sessions: about 19M distinct states, about four minutes. The second checks the same rules under `Restart::Handoff` over three sessions: about 3.4M states, under a minute. Each session picks whether its version answers the credential. All pass at the sync commit. Nightly runs every config here and fails if a config with an `\* Open finding:` line passes. The `VIEW` counts states that differ only in what nothing reads again as one: a closed session's details unless it is still the live one, a deadline of a phase the policy left, and where no dial is headed.

## Open findings

Expand All @@ -40,17 +41,17 @@ Follow Reading a failure in `rs/moq-net/verify/README.md`. Replay the path on th

## Coverage

Sync commit: `27b46ef35bdf284ba61158521723768436cd8460`. Run `git log 27b46ef35b.. -- rs/moq-net/src/reconnect.rs rs/moq-net/src/reconnect/ rs/moq-tokio/src/connection.rs` to see what changed since. Follow Coverage in `rs/moq-net/verify/README.md` after a change to a covered function.
Sync commit: `51e8538a84adacd16f91ef9ef6d54acfab7289db`. Run `git log 51e8538a84.. -- rs/moq-net/src/reconnect.rs rs/moq-net/src/reconnect/ rs/moq-tokio/src/connection.rs` to see what changed since. Follow Coverage in `rs/moq-net/verify/README.md` after a change to a covered function.

| Code | Model |
| --- | --- |
| `rs/moq-net/src/reconnect.rs` `Reconnect::poll` (queue, predecessor, phases), `follow` | `Pop`, `Retire`, `IdleClose`, `FollowPred`, `Dial`, `Abandon`, `BackoffEnds`, `LiveEnds`, `ProbeAsk`, `ProbeAbandon` |
| `rs/moq-net/src/reconnect.rs` `established`, set by `end` and by a GOAWAY in `poll`, and `walk_failed` and `closed` failing fast until it is set | `established`, `EndGoaway`, `LiveEnds`, `Failed`, `Abandon`, `EndClosed` |
| `rs/moq-net/src/reconnect.rs` `Reconnect::poll` (queue, predecessor, phases), `follow` | `Pop`, `Retire`, `IdleClose`, `FollowPred`, `Dial`, `Abandon`, `BackoffEnds`, `Establish`, `LiveEnds`, `ProbeAsk`, `ProbeAbandon` |
| `rs/moq-net/src/reconnect.rs` `established`, set in `poll` by a GOAWAY, the session's acceptance, or on a silent version the healthy bar, and `walk_failed` and `closed` failing fast until it is set | `established`, the session's `accepted`, the session's `silent` (`Session::is_silent`), `Healthy`, `Ages`, `EndGoaway`, `LiveEnds`, `Failed`, `Abandon`, `EndClosed` |
| `rs/moq-net/src/reconnect.rs` `connected`, `fallback`, `failed`, `probed` | `Connected`, `Failed`, `ProbeFails`, `ProbeGetsThrough` |
| `rs/moq-net/src/reconnect.rs` `end`, `closed`, `done`, `Predecessor` | `EndGoaway`, `EndClosed`, `Done`, `Retire`, `IdleClose` |
| `rs/moq-net/src/reconnect.rs` `Restart::Handoff` | `LiveEnds` and `WaitOut` with `Restart = "handoff"` (`RestartHandoff.cfg`) |
| `rs/moq-net/src/reconnect/redirect.rs` `Redirect::target` | `Refused` and `Endpoints` |
| `rs/moq-tokio/src/connection.rs` `run`, `Shared::connected`, `migrating`, `retired`, `offline`, `end` | `Connected`, `Apply`, `OnMigrating`, `OnRetired`, `OnOffline`, `OnDone` |
| `rs/moq-tokio/src/connection.rs` `run`, `Shared::connected`, `migrating`, `retired`, `offline`, `end` | `Connected`, `Apply`, `OnEstablished`, `OnMigrating`, `OnRetired`, `OnOffline`, `OnDone` |

## Not covered

Expand Down
5 changes: 3 additions & 2 deletions dart/moq/lib/src/aliases.dart
Original file line number Diff line number Diff line change
Expand Up @@ -299,8 +299,9 @@ typedef ConnectionState = MoqConnectionState;

/// Retry pacing for the automatic reconnect: initial delay, multiplier, ceiling, and give-up window.
/// A null field keeps its default, zero means zero (retry at once, or give up
/// at the first failure), and `maxUnlimited` lifts the ceiling. Until a session
/// has stayed up past 1s or been drained by a GOAWAY, a failed dial or a closed
/// at the first failure), and `maxUnlimited` lifts the ceiling. Until the peer
/// has accepted a session's credential or drained a session with a GOAWAY
/// (or, on moq-lite 03/04, which never answer it, a session stayed up 1s), a failed dial or a closed
/// session, such as a refused credential, ends the connection with its error
/// rather than retrying.
typedef Backoff = MoqBackoff;
Expand Down
5 changes: 3 additions & 2 deletions dart/moq/lib/src/client.dart
Original file line number Diff line number Diff line change
Expand Up @@ -60,8 +60,9 @@ final class ConnectOptions {
/// The WebSocket fallback raced against QUIC for `http(s)` URLs.
final WebSocketConfig? websocket;

/// Set true for a one-shot dial. By default a session that stayed up past 1s
/// or was drained by a GOAWAY redials with backoff whenever the transport
/// Set true for a one-shot dial. By default a session whose credential the peer accepted,
/// or that the peer drained with a GOAWAY (or, on moq-lite 03/04, which never answer it,
/// that stayed up 1s), redials with backoff whenever the transport
/// drops; before then, a failed dial or a closed session, such as a refused
/// credential, ends it with that error instead.
final bool once;
Expand Down
7 changes: 4 additions & 3 deletions doc/bin/gstreamer.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,8 @@ codec config, a pad requested again, or a stream resumed after EOS publishes as
`url`, `broadcast`, `linger`, `connect-version`, `connect-websocket-enabled`, `tls-disable-verify`, `quic-idle-timeout`, `quic-keylog`,
`quic-keep-alive`, and read-only `status`, `connected`, `moq-version`, and
`estimated-send-rate`, `estimated-recv-rate`, `connection-stats`, and
`sessions`. Once a session has stayed up past a second, the sink reconnects for as long as
`sessions`. Once the relay has accepted a session (on moq-lite 03/04, which never answer, once
one has stayed up for a second), the sink reconnects for as long as
the pipeline runs, whatever ends each session. Before then it reports `failed` and posts an
error instead of retrying: a first connect that reaches no relay, or a session the relay
refuses, such as for a rejected token.
Expand Down Expand Up @@ -172,8 +173,8 @@ its pads without EOS until it is announced again, so the pipeline does not end
on its own. Losing the relay connection also holds the pads: `moqsrc` redials
without a retry deadline and resumes when the broadcast returns. A first connect
that reaches no relay posts an error rather than retrying, as does a first
connection the relay refuses, or a session it closes before the connection has
stayed up for a second. Once playback has begun, a session the relay closes is
connection the relay refuses, or a session it closes before accepting it (on
moq-lite 03/04, which never answer, before it has stayed up for a second). Once playback has begun, a session the relay closes is
redialed, whatever its code, and a refused redial is retried like any other
failure. A refused path or catalog, malformed input or catalog, or a catalog its
publisher ended with an application code posts an error. A media track its
Expand Down
2 changes: 1 addition & 1 deletion doc/lib/cpp/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -257,7 +257,7 @@ Set `ClientConfig::tokens` instead of putting the credential in the URL. The fir

## Stats

`session->stats()` reports the transport counters, each a `std::optional` that is empty when the transport does not report it, plus the negotiated protocol in `version`. Connect returns a connecting session. Read `session->state()` and wait with `state_changed(state.revision)` to observe its reconnects (until a session has stayed up past 1s or been drained by a GOAWAY, a failed dial or a closed session, such as a refused credential, ends the session with that error rather than retrying); independent watchers keep their own revisions.
`session->stats()` reports the transport counters, each a `std::optional` that is empty when the transport does not report it, plus the negotiated protocol in `version`. Connect returns a connecting session. Read `session->state()` and wait with `state_changed(state.revision)` to observe its reconnects (until the peer has accepted a session's credential or drained a session with a GOAWAY (or, on moq-lite 03/04, which never answer it, a session stayed up 1s), a failed dial or a closed session, such as a refused credential, ends the session with that error rather than retrying); independent watchers keep their own revisions.

## Shutdown

Expand Down
2 changes: 1 addition & 1 deletion doc/lib/dart/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -160,7 +160,7 @@ shows which module holds each.
- **Decoded frames hold decoder buffers.** `dispose()` each frame from a `video.Consumer` promptly rather than waiting for the garbage collector, or the decoder stalls. `resize` is best effort, so read each frame's `width()` and `height()`.
- **Closing.** `await moq.close()` drains for up to one second and reports its result. `session.shutdown()` requests the drain synchronously; `await session.closed()` waits for its result. `session.cancel(code: 0)` closes at once. Finish or abort live tracks first. Awaiting cancellation of an announcement, grant, or request subscription releases its pending native read. Announcements and grants also release their consumer; server listeners leave their shared server usable. moq-lite-05 and newer wait for the peer to receive finished tails; older Lite versions and IETF wait only for transport ACKs.
- **Ending cleanly.** When the input ends, finish every track, then call `finish()` on its `CatalogProducer` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `broadcast.close()` or disposing its `MoqRoute` takes it offline. How long to keep it up is yours to decide. A track still open at the close ends with `Unroutable` (`Internal` over moq-transport, which has no such code), and one released without a finish ends `Dropped`, which readers see as `Internal`. Readers follow a publisher's runs by announcement, not by that error: see [identity and recovery](/concept/identity).
- **Stats.** `session.stats()` reports `rtt`, `estimatedSendRateBps`, and the byte and packet counters (`bytesSent`, `bytesReceived`, `bytesLost`, `packetsSent`, `packetsReceived`, `packetsLost`), and `datagramsUnrouted`, the datagrams received for a subscription with no datagram track, reported only on moq-lite 05 and later, which carry datagrams. A field is `null` when the transport does not report it, which is not the same as zero. `version` names the negotiated protocol. Connect returns a connecting session; read its coherent `state()` snapshot and wait with that snapshot's revision to observe reconnects. Until a session has stayed up past 1s or been drained by a GOAWAY, a failed dial or a closed session, such as a refused credential, ends the session with that error rather than retrying. Each watcher keeps its own revision. Hold the owned `BandwidthConsumer` returned by `session.recvBandwidth()` to receive bandwidth estimates. `rate()` reads the current estimate in bits per second and `rateChanged()` waits for a new one. Release the consumer or call `cancel()` when finished; releasing the last consumer stops PROBE; the session and stats snapshots do not request it. Client consumers survive reconnects and report no estimate while disconnected.
- **Stats.** `session.stats()` reports `rtt`, `estimatedSendRateBps`, and the byte and packet counters (`bytesSent`, `bytesReceived`, `bytesLost`, `packetsSent`, `packetsReceived`, `packetsLost`), and `datagramsUnrouted`, the datagrams received for a subscription with no datagram track, reported only on moq-lite 05 and later, which carry datagrams. A field is `null` when the transport does not report it, which is not the same as zero. `version` names the negotiated protocol. Connect returns a connecting session; read its coherent `state()` snapshot and wait with that snapshot's revision to observe reconnects. Until the peer has accepted a session's credential or drained a session with a GOAWAY (or, on moq-lite 03/04, which never answer it, a session stayed up 1s), a failed dial or a closed session, such as a refused credential, ends the session with that error rather than retrying. Each watcher keeps its own revision. Hold the owned `BandwidthConsumer` returned by `session.recvBandwidth()` to receive bandwidth estimates. `rate()` reads the current estimate in bits per second and `rateChanged()` waits for a new one. Release the consumer or call `cancel()` when finished; releasing the last consumer stops PROBE; the session and stats snapshots do not request it. Client consumers survive reconnects and report no estimate while disconnected.
- **Viewers.** `client.viewers()` divides the connection's receive estimate among the broadcasts you watch, max-min fair by each one's ceiling. `watch(maxBps: ...)` returns a `Viewer` claiming up to what the largest rendition the player would switch to needs; `rate()` reads its slice in bits per second, `null` while there is no estimate, so hold the current selection. `update(maxBps: ...)` changes the ceiling, such as when the catalog enables or disables a rendition. Holding a viewer requests PROBE, and the session sends the viewers' summed ceilings as the PROBE target; `dispose()` it once the broadcast stops being watched. `setTarget(targetBps: ...)` sends another target, `0` sends none, and `null` follows the viewers again. Ceilings or a target past 2^53 - 1 bps, the most a PROBE target carries, throw `OutOfRangeMoqException`. Client viewers survive reconnects and read `null` while disconnected.
- **Authorization.** On `moq-lite-07-wip` (opt in with `ConnectOptions(versions: ...)`), listen to `moq.grants().updates()` for the `Grant` the relay sent back and each change, `null` until it answers and while a client session reconnects.
- **Tokens.** Pass `ConnectOptions(tokens: [...])` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. `moq.tokens().set_(tokens: [...])` replaces them before they expire: the next dial presents them, a live AUTH session at once. `await tokens().answered()` returns once the relay accepts them and throws its refusal with the relay's code. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. For a per-request token, `moq.credential(token)` returns a `Credential` that `route.setAuth(credential: credential)` or `claim.setAuth(credential: credential)` names (`null` for none); setting a new one renews the announcement in place. Only the session that minted it carries it, a client session across its reconnects; another session announcing the same route uses its own scope. On moq-transport `answered` resolves at once, since only the request carries the token; on moq-lite the token rides AUTH instead (07 only, unsupported before), so `answered` is the peer's verdict and the grant joins the whole session's, not only the named route's. `await credential.answered()` throws the peer's refusal, and `credential.cancel()` withdraws it unless a route or claim still names it.
Expand Down
Loading