Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
69a914d
quest: open the transport-upgrade line
kixelated Sep 25, 2026
d8cde38
Merge origin/dev into quest/m1/transport-upgrade/README
kixelated Sep 25, 2026
c28102a
Merge origin/main into quest/m1/transport-upgrade/README
kixelated Sep 25, 2026
cf3bb19
feat(tokio)!: upgrade a WebSocket fallback session to WebTransport (#…
kixelated Sep 25, 2026
8b8519a
quest(transport-upgrade): WebSocket upgrade edge cases (#4204)
kixelated Sep 26, 2026
abc5f71
quest(transport-upgrade): claim polish
kixelated Sep 26, 2026
54e1787
fix(tokio): fall back to the pending QUIC dial when the WebSocket han…
kixelated Sep 26, 2026
cacaf25
quest(transport-upgrade): add closed-fallback and js-qmux-finish foll…
kixelated Sep 26, 2026
3d38d33
fix(tokio): classify a double handshake failure as a race loss
kixelated Sep 27, 2026
c57de66
Merge origin/dev into quest/m1/transport-upgrade/README
kixelated Oct 1, 2026
e156cd0
Merge remote-tracking branch 'origin/quest/m1/transport-upgrade/READM…
kixelated Oct 1, 2026
b4eaf83
fix(tokio): keep a QUIC error that predates the WebSocket win
kixelated Oct 1, 2026
99b1240
Merge pull request #4296 from moq-dev/quest/m1/transport-upgrade/polish
kixelated Oct 1, 2026
e2d48f3
Merge origin/main into quest/m1/transport-upgrade/README
kixelated Oct 5, 2026
c3b0981
Merge origin/main into quest/m1/transport-upgrade/README
kixelated Oct 5, 2026
f4c26d8
Merge remote-tracking branch 'origin/main' into tu-merge-main
kixelated Oct 6, 2026
f7165cf
quest(flat-lines): transport-upgrade lands
kixelated Oct 6, 2026
4e8b459
fix(tokio): a healthy WebSocket tenure resets the retry window on upg…
kixelated Oct 6, 2026
705bedb
Merge origin/main into quest/m1/transport-upgrade/README
kixelated Oct 6, 2026
4c181eb
fix(tokio): upgrade to QUIC only once the relay admits the session
kixelated Oct 6, 2026
29e8fc2
Merge origin/main into quest/m1/transport-upgrade/README
kixelated Oct 6, 2026
e382784
fix(net): a closed session is no longer accepted
kixelated Oct 6, 2026
e423dc4
fix(tokio): drop a QUIC upgrade that already received GOAWAY
kixelated Oct 6, 2026
892ccc7
fix(net): name peer SETUP completion accurately
kixelated Oct 6, 2026
76e0e8e
style: format SETUP and transport race tests
kixelated Oct 6, 2026
b08eca2
Merge remote-tracking branch 'origin/main' into codex/transport-setup…
kixelated Oct 6, 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
4 changes: 3 additions & 1 deletion dart/moq_ffi/lib/src/moq.dart
Original file line number Diff line number Diff line change
Expand Up @@ -3975,7 +3975,7 @@ class LiveMoqAnnounceEvent extends MoqAnnounceEvent {
}
}

enum MoqTransport { quic, iroh, webSocket, tcp, unix }
enum MoqTransport { quic, iroh, webSocket, tcp, unix, webTransport }

class FfiConverterMoqTransport {
static LiftRetVal<MoqTransport> read(Uint8List buf) {
Expand All @@ -3991,6 +3991,8 @@ class FfiConverterMoqTransport {
return LiftRetVal(MoqTransport.tcp, 4);
case 5:
return LiftRetVal(MoqTransport.unix, 4);
case 6:
return LiftRetVal(MoqTransport.webTransport, 4);
default:
throw UniffiInternalError(
UniffiInternalError.unexpectedEnumCase,
Expand Down
6 changes: 5 additions & 1 deletion doc/concept/transport.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,11 @@ connection (`wss://`) and keep whichever wins. A small multiplexer,
[qmux](/draft/qmux-websocket), carries MoQ streams over the socket. It works
everywhere but cannot escape TCP head-of-line blocking, so priority and resets
only help once bytes leave the TCP queue. The fallback is automatic in every
client; the relay enables it with `[web.https]`.
client; the relay enables it with `[web.https]`. A native Rust client that lands on
WebSocket keeps dialing QUIC and moves the session onto it once the QUIC
session receives the peer's SETUP, staying on WebSocket if the relay refuses it
before SETUP. This crate's relays send SETUP after admission; other servers may
still refuse afterward.

## Raw QUIC (native)

Expand Down
6 changes: 5 additions & 1 deletion doc/lib/rs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,11 @@ URLs may be `https://` (WebTransport, with raw QUIC preferred for native),
`moql://`/`moqt://` (raw QUIC), or `iroh://`. A `?jwt=` query carries the
token. `http://` is for a relay on localhost only: it fetches the certificate
fingerprint unauthenticated before upgrading, so never send a token over it. Connections race
QUIC against WebSocket and remember which won.
QUIC against WebSocket and remember which won. When WebSocket wins, a `Connection` keeps
dialing QUIC and moves onto it once the relay admits that session, handing live tracks over
at a group boundary and draining the WebSocket session; `Connection::transport()` reports
which is live. A refused or stalled QUIC session leaves the WebSocket session serving, and
moq-lite-03 and -04, which give no sign of admission, never upgrade.

The `Default::default()` above is the QUIC transport section, and the same value
serves a dial and a listener:
Expand Down
9 changes: 9 additions & 0 deletions doc/lib/rs/moq-net.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,15 @@ let (session, driver) = client.connect(now, transport).await?;
tokio::spawn(moq_net::time::run(driver));
```

On moq-lite-05+ and moq-transport draft 17+, `Client::connect` returns before
the server's SETUP arrives, so a request made at once may still be
refused along with it. `session.setup().await` waits for the server's SETUP
and returns the close reason if the session is already closed, even after SETUP. A moq-rs
server sends its SETUP only once it admits the client; neither protocol
requires that, so another server may still refuse afterward. Older versions
read that SETUP during the handshake and resolve at once, except moq-lite-03
and -04, which carry none and return `Error::Unsupported`.

A custom event loop calls `driver.poll(now, waiter)` with a nondecreasing
`moq_net::time::Instant`. `Ok(Some(at))` asks to be polled again by `at` or
on external activity, `Ok(None)` only on external activity, and `Err` is the
Expand Down
6 changes: 6 additions & 0 deletions doc/setup/upgrade.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,12 @@ These land with the next breaking release, not the 2026-09-23 train.
broadcast that ends with media queued behind an undescribed track is an error
rather than an empty `Ok(None)`. Restart the export to pick up a new
rendition.
- **moq-tokio's `Transport` names WebTransport.** `moq_tokio::server::Transport`
is `moq_tokio::Transport`, with no re-export. A WebTransport session reports
`Transport::WebTransport` (`"webtransport"` in logs) instead of `Quic`, which
now means raw QUIC only, and `Connection::transport()` reports the live
transport. The bindings' `MoqTransport` gains a `WebTransport` case, so an
exhaustive `switch` or `when` needs one more arm.
- **moq-net has no `VarInt`.** Varints are plain `u64`s:
`VarInt::decode_quic(buf)?.into_inner()` is `moq_net::varint::decode_quic(buf)?`,
and `VarInt::try_from(v)?.encode_quic(buf)` is
Expand Down
2 changes: 2 additions & 0 deletions go/wrapper/server.go
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@ const (
TransportTCP = ffi.MoqTransportTcp
// TransportUnix is a session that arrived over a Unix domain socket.
TransportUnix = ffi.MoqTransportUnix
// TransportWebTransport is a session that arrived over WebTransport (HTTP/3).
TransportWebTransport = ffi.MoqTransportWebTransport
)

// Request is an incoming session that can be accepted (Accept) or rejected (Reject).
Expand Down
2 changes: 1 addition & 1 deletion quest/m1/quest-flat-lines.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ Remaining:
#4403 wildcard, #4034 archive, #4039 auth, #4079 cpp, #4519 ffi-shape,
#4080 obs-moq-video, #4133 qos (held until
[Lag across a splice](/quest/m1/qos/lag-splice.md) is fixed),
#4180 transport-upgrade, #4640 tstd. #4162 (audio-jitter-target), #4437 rs2ts
#4640 tstd. #4162 (audio-jitter-target), #4180 (transport-upgrade), #4437 rs2ts
(with #4438 folded in), and #4653 (test-flakes-2) landed.
- Fold #4255 (archive/track-timeline) into the archive branch before #4034
lands; as of the 2026-10-05 audit it has not happened and #4034 is a draft.
Expand Down
11 changes: 9 additions & 2 deletions quest/m1/transport-upgrade/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,13 @@ that.
Shared decisions:

- The race returns the winner plus the still-pending QUIC dial when WebSocket
wins. The QUIC handshake timeout bounds that dial; no extra deadline.
wins. The attempt's connect deadline bounds that dial; no extra deadline.
- The swap waits for the peer's SETUP on the QUIC session
(`moq_net::Session::setup`) within that same deadline; until
then the WebSocket session gets no GOAWAY. A refused or stalled QUIC session
is dropped and WebSocket keeps serving. moq-lite-03 and -04 carry no server
SETUP, so they never upgrade. This crate's servers send SETUP after admission;
other servers may send it before admission and still refuse afterward.
- On a successful upgrade the "WebSocket won" memo (`WEBSOCKET_WON` in
`moq-tokio`, `websocketWon` in `js/net`) forgets the URL: QUIC works on this
network, so the head start comes back. Otherwise a network where WebSocket
Expand All @@ -58,5 +64,6 @@ Shared decisions:

## Required

- [Rust](/quest/m1/transport-upgrade/rust.md) - moq-tokio keeps the QUIC dial after WebSocket wins and migrates through the existing Draining path
- [JavaScript](/quest/m1/transport-upgrade/js.md) - js/net keeps the WebTransport dial after WebSocket wins and migrates through the client-goaway handover
- [Closed fallback](/quest/m1/transport-upgrade/closed-fallback.md) - a WebSocket session that closes right after connecting falls back to the pending QUIC dial instead of redialing
- [JS qmux finish](/quest/m1/transport-upgrade/js-qmux-finish.md) - `@moq/qmux` reports a cleanly finished send stream as closed without error
30 changes: 30 additions & 0 deletions quest/m1/transport-upgrade/closed-fallback.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# [S] Fall back to QUIC when the WebSocket session closes at once

## Goal

When WebSocket wins the dial race and its session closes right after
connecting, the `Connection` moves onto the QUIC dial that is still pending
instead of dropping it and redialing. On moq-lite and IETF draft 17+ the
client handshake does not wait for the server, so a server refusing the
WebSocket session looks like this rather than like a handshake failure, which
already falls back.

## Plan

- Today `run_session` in `moq-tokio`'s `connection.rs` returns when the
WebSocket session closes, and the pending upgrade is dropped. The redial
starts a fresh QUIC dial and has lost QUIC's head start.
- Decide what counts as "at once". The unhealthy-session threshold that
already feeds the backoff may be the right line. Keep the connect deadline
that bounds the pending dial as the only deadline.
- An auth close on the WebSocket session is probably still terminal, the way
it is for a lone session. Check how the race treats a mixed auth pair and
match it.
- Test with the held-QUIC forwarder in the connection tests, as the handshake
fallback test does, with a default moq-lite client.

Public API: none. Wire: none.

## Related

- [#4296](https://github.com/moq-dev/moq/pull/4296) - the handshake-failure fallback this extends
22 changes: 22 additions & 0 deletions quest/m1/transport-upgrade/js-qmux-finish.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# [XS] Clean finish in @moq/qmux

## Goal

`@moq/qmux` reports a send stream that finished cleanly as closed without
error, so `@moq/net` does not treat a delivered GOAWAY or SETUP as a failure
over the WebSocket fallback.

## Plan

The Rust qmux crate reported every finished stream as `connection closed`
(fixed in moq-dev/web-transport#402). Check whether the TypeScript peer in
`moq-dev/web-transport` (`js/qmux`) has the same bug, and whether `@moq/net`
waits on a finished writable anywhere it would notice. If it does, fix it
there with a regression test, release, and bump `@moq/qmux` in `js/net`. If
not, note that in the PR that deletes this quest.

Public API: none. Wire: none.

## Related

- [JavaScript upgrade](/quest/m1/transport-upgrade/js.md) - sends a GOAWAY over the WebSocket session on every upgrade
8 changes: 7 additions & 1 deletion quest/m1/transport-upgrade/js.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,12 @@ session to close on its own or at the handover cap. See the
may not name a redirect URI, and an empty one is legal) and closes at the
configured cap. A WebTransport attempt that fails after WebSocket won is logged at
debug and the session stays on WebSocket.
- Swap only once the server's SETUP arrives on the WebTransport session: mirror Rust's
`moq_net::Session::setup()` in `js/net` (resolves on the server's SETUP,
rejects with the close reason if already closed, even after SETUP) and await it inside the
connect deadline. A refusal, a stall, or moq-lite-03/-04 (no server SETUP)
keeps WebSocket with no GOAWAY sent. This crate's servers send SETUP after
admission; other servers may still refuse afterward.
- A self-sent GOAWAY must gate new requests on the old session too, not only
a received one: [JS GOAWAY requests](/quest/m1/js-goaway-requests.md)
covers the received case, so check it also covers this path.
Expand All @@ -40,7 +46,7 @@ session to close on its own or at the handover cap. See the
group across the upgrade, the WebSocket session closes within the cap, and
the next connect to the same URL gives WebTransport the head start again;
with no delay, WebTransport wins and no WebSocket session is ever opened.
- Public API: none beyond what client-goaway adds; `transportOf` already
- Public API: the `setup` mirror, if it is exported; `transportOf` already
reports the live transport. Update `doc/lib/js` where the fallback race is
described.

Expand Down
49 changes: 0 additions & 49 deletions quest/m1/transport-upgrade/rust.md

This file was deleted.

12 changes: 6 additions & 6 deletions rs/moq-cli/src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -253,9 +253,9 @@ async fn serve_client(
}

/// Whether ordinary clients may use this transport on the shared LAN server.
fn is_public_transport(transport: moq_tokio::server::Transport, public_quic: bool) -> bool {
fn is_public_transport(transport: moq_tokio::Transport, public_quic: bool) -> bool {
match transport {
moq_tokio::server::Transport::Tcp | moq_tokio::server::Transport::Unix => true,
moq_tokio::Transport::Tcp | moq_tokio::Transport::Unix => true,
_ => public_quic,
}
}
Expand Down Expand Up @@ -1031,9 +1031,9 @@ mod tests {

#[test]
fn explicit_stream_listeners_are_public_without_exposing_mesh_quic() {
assert!(is_public_transport(moq_tokio::server::Transport::Tcp, false));
assert!(is_public_transport(moq_tokio::server::Transport::Unix, false));
assert!(!is_public_transport(moq_tokio::server::Transport::Quic, false));
assert!(is_public_transport(moq_tokio::server::Transport::Quic, true));
assert!(is_public_transport(moq_tokio::Transport::Tcp, false));
assert!(is_public_transport(moq_tokio::Transport::Unix, false));
assert!(!is_public_transport(moq_tokio::Transport::Quic, false));
assert!(is_public_transport(moq_tokio::Transport::Quic, true));
}
}
25 changes: 16 additions & 9 deletions rs/moq-ffi/src/server.rs
Original file line number Diff line number Diff line change
Expand Up @@ -202,7 +202,7 @@ struct RequestState {
/// The network transport carrying an incoming session.
#[derive(Clone, Copy, Debug, Eq, PartialEq, uniffi::Enum)]
pub enum MoqTransport {
/// QUIC, either directly or through WebTransport over HTTP/3.
/// Raw QUIC, negotiating a MoQ ALPN directly.
Quic,
/// An Iroh QUIC connection.
Iroh,
Expand All @@ -212,18 +212,21 @@ pub enum MoqTransport {
Tcp,
/// A Unix domain socket using qmux framing.
Unix,
/// WebTransport over HTTP/3 on QUIC.
WebTransport,
}

impl TryFrom<moq_tokio::server::Transport> for MoqTransport {
impl TryFrom<moq_tokio::Transport> for MoqTransport {
type Error = MoqError;

fn try_from(value: moq_tokio::server::Transport) -> Result<Self, Self::Error> {
fn try_from(value: moq_tokio::Transport) -> Result<Self, Self::Error> {
Ok(match value {
moq_tokio::server::Transport::Quic => Self::Quic,
moq_tokio::server::Transport::Iroh => Self::Iroh,
moq_tokio::server::Transport::WebSocket => Self::WebSocket,
moq_tokio::server::Transport::Tcp => Self::Tcp,
moq_tokio::server::Transport::Unix => Self::Unix,
moq_tokio::Transport::Quic => Self::Quic,
moq_tokio::Transport::Iroh => Self::Iroh,
moq_tokio::Transport::WebSocket => Self::WebSocket,
moq_tokio::Transport::Tcp => Self::Tcp,
moq_tokio::Transport::Unix => Self::Unix,
moq_tokio::Transport::WebTransport => Self::WebTransport,
_ => return Err(MoqError::Unsupported),
})
}
Expand All @@ -232,7 +235,7 @@ impl TryFrom<moq_tokio::server::Transport> for MoqTransport {
#[cfg(test)]
mod transport_tests {
use super::MoqTransport;
use moq_tokio::server::Transport;
use moq_tokio::Transport;

#[test]
fn converts_supported_transports() {
Expand All @@ -244,6 +247,10 @@ mod transport_tests {
);
assert_eq!(MoqTransport::try_from(Transport::Tcp).unwrap(), MoqTransport::Tcp);
assert_eq!(MoqTransport::try_from(Transport::Unix).unwrap(), MoqTransport::Unix);
assert_eq!(
MoqTransport::try_from(Transport::WebTransport).unwrap(),
MoqTransport::WebTransport
);
}
}

Expand Down
15 changes: 10 additions & 5 deletions rs/moq-net/src/client.rs
Original file line number Diff line number Diff line change
Expand Up @@ -203,6 +203,7 @@ impl Client {
start.recv_bandwidth,
crate::driver::Protocol::Lite(Box::new(start.driver)),
start.goaway,
start.setup,
))
}

Expand Down Expand Up @@ -259,7 +260,7 @@ impl Client {

// Draft-17+: SETUP is exchanged by the connection driver.
// We advertise the request path in our SETUP for URL-less transports.
let (protocol, goaway) = ietf::start(ietf::Config {
let (protocol, goaway, setup) = ietf::start(ietf::Config {
runtime: runtime.clone(),
session: session.clone(),
setup: None,
Expand All @@ -285,6 +286,7 @@ impl Client {
None,
crate::driver::Protocol::Ietf(protocol),
goaway,
setup,
));
}
Some(ALPN_16) => {
Expand Down Expand Up @@ -371,7 +373,7 @@ impl Client {
.copied()
.ok_or(Error::Version)?;

let (recv_bw, protocol, goaway) = match version {
let (recv_bw, protocol, goaway, setup) = match version {
Version::Lite(v) => {
let stream = stream.with_version(v);
let start = lite::start(lite::Config {
Expand All @@ -392,6 +394,7 @@ impl Client {
start.recv_bandwidth,
crate::driver::Protocol::Lite(Box::new(start.driver)),
start.goaway,
start.setup,
)
}
Version::Ietf(v) => {
Expand All @@ -410,7 +413,7 @@ impl Client {

let stream = stream.with_version(v);
// Draft 14-16: the path rode in the bidi SETUP above, not the uni one.
let (protocol, goaway) = ietf::start(ietf::Config {
let (protocol, goaway, setup) = ietf::start(ietf::Config {
runtime: runtime.clone(),
session: session.clone(),
setup: Some(stream),
Expand All @@ -427,11 +430,13 @@ impl Client {
peer_declared: Some(peer_declared),
early_unis: Vec::new(),
})?;
(None, crate::driver::Protocol::Ietf(protocol), goaway)
(None, crate::driver::Protocol::Ietf(protocol), goaway, setup)
}
};

Ok(Session::new(runtime, session, version, recv_bw, protocol, goaway))
Ok(Session::new(
runtime, session, version, recv_bw, protocol, goaway, setup,
))
}
}

Expand Down
Loading
Loading