diff --git a/.github/workflows/interop.yml b/.github/workflows/interop.yml index 0547c599c56..1bdc0ecbbca 100644 --- a/.github/workflows/interop.yml +++ b/.github/workflows/interop.yml @@ -65,6 +65,12 @@ jobs: run: nix develop --command just test max-age shell: bash -leo pipefail {0} + - name: Datagram tracks + id: datagram-tracks + if: ${{ !cancelled() && steps.setup.outcome == 'success' }} + run: nix develop --command just test datagram-tracks + shell: bash -leo pipefail {0} + - name: Stream limits over WebSocket id: stream-limits if: ${{ !cancelled() && steps.setup.outcome == 'success' }} @@ -217,6 +223,7 @@ jobs: "Rust cache": "${{ steps.rust-cache.outcome }}", "Playwright Chromium": "${{ steps.setup.outcome }}", "Optional publisher retention": "${{ steps.max-age.outcome }}", + "Datagram tracks": "${{ steps.datagram-tracks.outcome }}", "Stream limits over WebSocket": "${{ steps.stream-limits.outcome }}", "Relay fills": "${{ steps.relay-fill.outcome }}", "Receive credit recovery": "${{ steps.receive-credit.outcome }}", diff --git a/.github/workflows/release-gate.yml b/.github/workflows/release-gate.yml index b82aa57386d..e0a8f9d23c5 100644 --- a/.github/workflows/release-gate.yml +++ b/.github/workflows/release-gate.yml @@ -140,6 +140,8 @@ jobs: - "test/max-age/**" - "test/portrait/**" - "rs/moq-tokio/tests/integration/max_age.rs" + - "test/datagram-tracks/**" + - "rs/moq-tokio/tests/integration/datagram_tracks.rs" - "test/stream-limits/**" - "rs/moq-tokio/tests/integration/stream_limits.rs" - "test/relay-fill/**" diff --git a/js/net/src/connection/connect.test.ts b/js/net/src/connection/connect.test.ts index 1a8d2b5e234..63ca3039075 100644 --- a/js/net/src/connection/connect.test.ts +++ b/js/net/src/connection/connect.test.ts @@ -1063,12 +1063,7 @@ test("when the WebSocket wins, every WebTransport dial is closed", async () => { const originalStream = native.WebSocketStream; native.WebSocketStream = class { url: string; - opened = sleep(Nano.fromMilli(Milli(100))).then(() => ({ - readable: new ReadableStream(), - writable: new WritableStream(), - protocol: "qmux-01", - extensions: "", - })); + opened = sleep(Nano.fromMilli(Milli(100))).then(qmuxStreams); closed = new Promise(() => {}); constructor(url: string) { this.url = url; @@ -1105,12 +1100,7 @@ test("when WebTransport and WebSocket open in the same turn, the one not chosen const originalStream = native.WebSocketStream; native.WebSocketStream = class { url: string; - opened = opened.then(() => ({ - readable: new ReadableStream(), - writable: new WritableStream(), - protocol: "qmux-01", - extensions: "", - })); + opened = opened.then(qmuxStreams); closed = new Promise(() => {}); constructor(url: string) { this.url = url; @@ -1229,6 +1219,20 @@ test("an invalid timeout throws before touching the caller's signal", async () = await expect(connect(url, { timeout: -1 as Milli })).rejects.toThrow("invalid time: -1"); }); +/** An opened WebSocketStream whose QMux server sent only its TRANSPORT_PARAMETERS (all + * defaults), which a session's `ready` waits for. */ +function qmuxStreams() { + return { + readable: new ReadableStream({ + start: (controller) => + controller.enqueue(new Uint8Array([0xff, 0x51, 0x53, 0x30, 0x0d, 0x0a, 0x0d, 0x0a, 0])), + }), + writable: new WritableStream(), + protocol: "qmux-01", + extensions: "", + }; +} + type WebSocketDial = "hang" | "open" | { failAfter: Milli } | { openAfter: Milli }; // Their own host: a WebSocket that wins drops WebTransport's head start for its host and port afterwards. @@ -1243,12 +1247,7 @@ function webSocketPlan(clock: Manual, plan: (dial: number) => WebSocketDial) { const originalTransport = native.WebTransport; native.WebTransport = undefined; const dials: { at: number; closes: number }[] = []; - const streams = () => ({ - readable: new ReadableStream(), - writable: new WritableStream(), - protocol: "qmux-01", - extensions: "", - }); + const streams = qmuxStreams; native.WebSocketStream = class { url: string; opened: Promise; diff --git a/js/p2p/src/transport.test.ts b/js/p2p/src/transport.test.ts index 3764f70b8fc..fea9e5da024 100644 --- a/js/p2p/src/transport.test.ts +++ b/js/p2p/src/transport.test.ts @@ -94,7 +94,7 @@ test("the accepting side stays silent until the dialer's first record proves its await Promise.all([client.closed, server.closed]); }); -test("an accepted channel whose dialer stays silent still idles out without sending", async () => { +test("an accepted channel whose dialer stays silent closes at the handshake deadline without sending", async () => { const clock = new Manual(); const installed = clock.install(); try { @@ -102,11 +102,10 @@ test("an accepted channel whose dialer stays silent still idles out without send left.createDataChannel("moq", { ordered: true, protocol }); const server = Transport.accept({ peer: right.asPeer(), channel: right.incoming.asChannel(), protocol }); right.incoming.open(); - // The session starts on open, so its 30 s idle deadline runs while its first write waits. - await server.ready; - // The idle check polls every 5 s and skips ticks a single long jump would miss. - for (let i = 0; i < 7; i++) await clock.advance(Nano.fromMilli(Milli(5_000))); - await expect(server.closed).rejects.toThrow("idle timeout"); + // The session starts on open, so its 10 s handshake deadline runs while its first write + // waits on the silent dialer's parameters. + await clock.advance(Nano.fromMilli(Milli(11_000))); + await expect(server.closed).rejects.toThrow("handshake timeout"); expect(right.incoming.records).toEqual([]); expect(right.incoming.listeners.size).toBe(0); } finally { @@ -129,7 +128,12 @@ test("an accepted side that closes before hearing its dialer still closes gracef mock.left.channel.stream = false; mock.left.channel.open(); mock.right.incoming.open(); - await server.ready; + // Its `ready` waits for the dialer's lost parameters. The datagram writable starts once + // the session exists, which then starts on the open channel in pure microtask work. + const datagrams = server.datagrams.writable.getWriter(); + await datagrams.ready; + datagrams.releaseLock(); + for (let i = 0; i < 10; i++) await Promise.resolve(); server.close({ closeCode: 7, reason: "bye" }); // No clock advance: the close must not wait out qmux's flush timeout. expect(await client.closed).toEqual({ closeCode: 7, reason: "bye" }); diff --git a/js/p2p/src/transport.ts b/js/p2p/src/transport.ts index 89c3b75c935..85404c7e9ea 100644 --- a/js/p2p/src/transport.ts +++ b/js/p2p/src/transport.ts @@ -92,6 +92,9 @@ export class Transport implements WebTransport { }); this.ready = this.#session.then((session) => session.ready); void this.ready.catch((error) => { + // A session that started settles `closed` and closes the channel itself, gracefully + // when closed before its handshake finished. Only a channel that never opened has none. + if (this.#active) return; this.#closed.reject(error); this.#socket.close(); }); diff --git a/js/qmux/api/index.api.md b/js/qmux/api/index.api.md index c03b10a151b..17870d4a713 100644 --- a/js/qmux/api/index.api.md +++ b/js/qmux/api/index.api.md @@ -10,6 +10,7 @@ export interface BidirectionalStream extends WebTransportBidirectionalStream { } export interface Config { + handshakeTimeout?: number | null; idleTimeout?: number | null; maxDatagramFrameSize?: bigint | null; maxRecordSize?: bigint; diff --git a/js/qmux/src/session.test.ts b/js/qmux/src/session.test.ts index 805d4336584..e73afb94134 100644 --- a/js/qmux/src/session.test.ts +++ b/js/qmux/src/session.test.ts @@ -33,6 +33,7 @@ class FakePeer { #writeError: Error | undefined; #unblockWrites: (() => void) | undefined; #pongResolve?: () => void; + #writable: WritableStream; /** Raw chunks the Session has written. */ sent: Uint8Array[] = []; @@ -64,6 +65,7 @@ class FakePeer { } }, }); + this.#writable = writable; this.opened = Promise.resolve({ readable, writable, protocol, extensions: "" }); const closed = Promise.withResolvers<{ closeCode?: number; reason?: string }>(); this.closed = closed.promise; @@ -100,6 +102,10 @@ class FakePeer { } // --- test controls --- + /** Whether the session took the socket's writable, which it does as it starts. */ + get started(): boolean { + return this.#writable.locked; + } /** Wait until the session has handled all preceding inbound frames. */ barrier(): Promise { const pong = Promise.withResolvers(); @@ -178,6 +184,12 @@ async function waitFor(check: () => boolean, timeoutMs = 1000): Promise { } } +/** Wait until the session opened its socket. Its `ready` waits for the peer's transport + * parameters too, which most tests send later, if at all. */ +async function started(peer: FakePeer): Promise { + await waitFor(() => peer.started); +} + /** Yield a few macrotask turns so queued reads and any pending promise rejections * settle (an unhandled rejection surfaces at the end of the current turn). */ async function settle(turns = 5): Promise { @@ -269,17 +281,25 @@ describe("Session integration (scripted peer)", () => { } }); - test("handshake: sends TRANSPORT_PARAMETERS and resolves ready", async () => { + test("handshake: sends TRANSPORT_PARAMETERS and resolves ready on the peer's", async () => { const { session, peer } = connect(); + let ready = false; + void session.ready.then(() => { + ready = true; + }); + await started(peer); + await settle(); + expect(ready).toBe(false); + peer.send({ type: "transport_parameters", params: peerParams() }); await session.ready; - await waitFor(() => peer.has("transport_parameters")); + expect(session.datagrams.maxDatagramSize).toBeGreaterThan(0); session.close(); }); test("a uni stream write produces a STREAM frame on the wire", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; // createUnidirectionalStream blocks until the peer's stream-count credit arrives. const writable = await session.createUnidirectionalStream(); @@ -293,8 +313,8 @@ describe("Session integration (scripted peer)", () => { test("aborting after a write sends the transmitted byte count as final_size", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; const writable = await session.createUnidirectionalStream(); const writer = writable.getWriter(); @@ -309,8 +329,8 @@ describe("Session integration (scripted peer)", () => { test("aborting with a WebTransportError sends its streamErrorCode", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; const writable = await session.createUnidirectionalStream(); await writable.abort(new StreamError(26, "RESET_STREAM")); @@ -323,8 +343,8 @@ describe("Session integration (scripted peer)", () => { test("aborting with a plain error sends code 0", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; const writable = await session.createUnidirectionalStream(); await writable.abort(new Error("cancel")); @@ -343,8 +363,8 @@ describe("Session integration (scripted peer)", () => { ] as const) { test(`aborting a write parked on ${kind} credit sends RESET_STREAM at once`, async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams(params) }); + await session.ready; const writer = (await session.createUnidirectionalStream()).getWriter(); const write = settleTo(writer.write(new Uint8Array(10))); @@ -365,8 +385,8 @@ describe("Session integration (scripted peer)", () => { test("a send stream's bytes count as acknowledged once they reach the socket", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; await waitFor(() => peer.has("transport_parameters")); const stream = await session.createUnidirectionalStream(); const writer = stream.getWriter(); @@ -388,8 +408,8 @@ describe("Session integration (scripted peer)", () => { test("aborting a write queued behind a wedged socket doesn't wait for it to drain", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; await waitFor(() => peer.has("transport_parameters")); const writer = (await session.createUnidirectionalStream()).getWriter(); @@ -412,8 +432,8 @@ describe("Session integration (scripted peer)", () => { test("aborting a close queued behind a wedged socket resets the stream", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; await waitFor(() => peer.has("transport_parameters")); const writer = (await session.createUnidirectionalStream()).getWriter(); await writer.write(new Uint8Array(3)); @@ -440,8 +460,8 @@ describe("Session integration (scripted peer)", () => { test("aborting mid-write sends no more of that write", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; await waitFor(() => peer.has("transport_parameters")); const writer = (await session.createUnidirectionalStream()).getWriter(); @@ -468,8 +488,8 @@ describe("Session integration (scripted peer)", () => { const { session, peer } = connect(); try { - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; const uni = await session.createUnidirectionalStream(); await uni.abort(new Error("application closed uni stream")); @@ -497,8 +517,8 @@ describe("Session integration (scripted peer)", () => { test("cancelling with a WebTransportError sends its streamErrorCode as STOP_SENDING", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; const id = Stream.Id.create(0n, Stream.Dir.Uni, true); peer.send({ type: "stream", id, data: new Uint8Array([1, 2, 3]), fin: false }); @@ -516,8 +536,8 @@ describe("Session integration (scripted peer)", () => { test("a received RESET_STREAM errors the readable with the peer's code", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; const id = Stream.Id.create(0n, Stream.Dir.Uni, true); peer.send({ type: "stream", id, data: new Uint8Array([1, 2, 3]), fin: false }); @@ -546,8 +566,8 @@ describe("Session integration (scripted peer)", () => { test("a received STOP_SENDING errors the writable with the peer's code", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; const writable = await session.createUnidirectionalStream(); const writer = writable.getWriter(); @@ -567,8 +587,8 @@ describe("Session integration (scripted peer)", () => { test("a RESET_STREAM received first keeps the stream terminal", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; const id = Stream.Id.create(5n, Stream.Dir.Uni, true); peer.send({ type: "reset_stream", id, code: VarInt.from(0), finalSize: 0n }); @@ -593,8 +613,8 @@ describe("Session integration (scripted peer)", () => { // lower one. Tracking each skipped index would let one tiny frame make us // allocate (and loop) once per stream below it. const { session, peer } = connect({ maxStreamsUni: 1n << 40n }); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; const high = Stream.Id.create((1n << 40n) - 1n, Stream.Dir.Uni, true); peer.send({ type: "stream", id: high, data: new Uint8Array([1]), fin: true }); @@ -618,8 +638,8 @@ describe("Session integration (scripted peer)", () => { test("RESET_STREAM final_size consumes connection flow control", async () => { const { session, peer } = connect({ receiveWindow: 4n, streamReceiveWindow: 10n }); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; peer.send({ type: "reset_stream", @@ -635,8 +655,8 @@ describe("Session integration (scripted peer)", () => { test("RESET_STREAM final_size is cumulative with later stream data for MAX_DATA", async () => { const { session, peer } = connect({ receiveWindow: 10n, streamReceiveWindow: 10n }); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; // Three bytes do not cross the receive-window replenishment threshold. Eight // bytes on a second stream therefore exceed MAX_DATA (3 + 8 > 10), proving @@ -661,8 +681,8 @@ describe("Session integration (scripted peer)", () => { test("RESET_STREAM final_size replenishes connection credit once discarded", async () => { const { session, peer } = connect({ receiveWindow: 10n, streamReceiveWindow: 10n }); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; peer.send({ type: "reset_stream", @@ -679,8 +699,8 @@ describe("Session integration (scripted peer)", () => { test("draft-01 tolerates the legacy zero final_size after data", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; const id = Stream.Id.create(0n, Stream.Dir.Uni, true); peer.send({ type: "stream", id, data: new Uint8Array([1, 2, 3]), fin: false }); @@ -693,8 +713,8 @@ describe("Session integration (scripted peer)", () => { test("sequential stream writes and FIN carry increasing OFF values", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; const writable = await session.createUnidirectionalStream(); const writer = writable.getWriter(); @@ -714,8 +734,8 @@ describe("Session integration (scripted peer)", () => { test("contiguous receive offsets are delivered in order", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; const id = Stream.Id.create(0n, Stream.Dir.Uni, true); peer.send({ type: "stream", id, offset: 0n, data: new Uint8Array([1, 2]), fin: false }); @@ -739,8 +759,8 @@ describe("Session integration (scripted peer)", () => { ] as const) { test(`a STREAM frame with ${name} closes the session`, async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; const id = Stream.Id.create(0n, Stream.Dir.Uni, true); peer.send({ type: "stream", id, offset: 0n, data: new Uint8Array([1, 2]), fin: false }); @@ -754,8 +774,8 @@ describe("Session integration (scripted peer)", () => { test("a FIN at the wrong offset closes the session", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; const id = Stream.Id.create(0n, Stream.Dir.Uni, true); peer.send({ type: "stream", id, offset: 0n, data: new Uint8Array([1, 2]), fin: false }); @@ -767,8 +787,8 @@ describe("Session integration (scripted peer)", () => { test("a new stream must start at offset zero", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; peer.send({ type: "stream", @@ -786,8 +806,8 @@ describe("Session integration (scripted peer)", () => { // Senders released before offsets were encoded omit OFF on every frame, // which reads as offset zero. Their frames are contiguous by construction. const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; // 0x0a = STREAM | LEN, 0x0b = STREAM | LEN | FIN; server-initiated uni id 3. peer.sendRaw(new Uint8Array([0x0a, 0x03, 0x02, 1, 2])); @@ -820,8 +840,8 @@ describe("Session integration (scripted peer)", () => { test("a peer that pings without reading gets only its newest ping answered", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; await waitFor(() => peer.has("transport_parameters")); // The peer stops reading but keeps pinging. Queuing a response per request @@ -850,7 +870,7 @@ describe("Session integration (scripted peer)", () => { const installed = clock.install(); try { const { session, peer } = connect({ idleTimeout: 300 }); - await session.ready; + await started(peer); await waitFor(() => peer.has("transport_parameters")); peer.send({ type: "transport_parameters", params: peerParams() }); await settle(); @@ -907,7 +927,7 @@ describe("Session integration (scripted peer)", () => { idleTimeout: undefined, maxDatagramFrameSize: undefined, }); - await session.ready; + await started(peer); await waitFor(() => peer.has("transport_parameters")); const frame = peer .received() @@ -922,8 +942,13 @@ describe("Session integration (scripted peer)", () => { }); test("disabled config uses null and invalid durations fail before opening", () => { - for (const idleTimeout of [0, -1, 1.5, NaN, Infinity, Number.MAX_SAFE_INTEGER + 1]) { - expect(() => new Session("https://example/test", { config: { idleTimeout } })).toThrow("idleTimeout"); + for (const value of [0, -1, 1.5, NaN, Infinity, Number.MAX_SAFE_INTEGER + 1]) { + expect(() => new Session("https://example/test", { config: { idleTimeout: value } })).toThrow( + "idleTimeout", + ); + expect(() => new Session("https://example/test", { config: { handshakeTimeout: value } })).toThrow( + "handshakeTimeout", + ); } expect(() => new Session("https://example/test", { config: { maxDatagramFrameSize: 0n } })).toThrow( "maxDatagramFrameSize", @@ -940,8 +965,8 @@ describe("Session integration (scripted peer)", () => { test("a failed write closes the session even if the socket never reports closing", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; await waitFor(() => peer.has("transport_parameters")); peer.failWrites(new Error("broken pipe")); @@ -953,8 +978,8 @@ describe("Session integration (scripted peer)", () => { test("a STREAM frame on a bidi stream we never opened closes the session", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; // Client-initiated bidi index 0: our role, but we never opened it. peer.send({ @@ -971,8 +996,8 @@ describe("Session integration (scripted peer)", () => { test("a RESET_STREAM on a stream we never opened closes the session", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; peer.send({ type: "reset_stream", @@ -987,8 +1012,8 @@ describe("Session integration (scripted peer)", () => { test("a late STREAM frame on a bidi stream we opened and stopped reading is dropped", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; const bidi = await session.createBidirectionalStream(); await bidi.readable.cancel(); @@ -1010,7 +1035,7 @@ describe("Session integration (scripted peer)", () => { // qmux-01 doesn't require TRANSPORT_PARAMETERS first, so a peer may open a // stream before them. Its own bidi stream is limited by its bidi_local. const { session, peer } = connect(); - await session.ready; + await started(peer); const id = Stream.Id.create(0n, Stream.Dir.Bi, true); peer.send({ type: "stream", id, offset: 0n, data: new Uint8Array([1]), fin: false }); @@ -1063,8 +1088,8 @@ describe("Session integration (scripted peer)", () => { test("STOP_SENDING fails a bidi write parked on stream credit", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams({ initialMaxStreamDataBidiRemote: 0n }) }); + await session.ready; const bidi = await session.createBidirectionalStream(); const write = settleTo(bidi.writable.getWriter().write(new Uint8Array(10))); @@ -1078,8 +1103,8 @@ describe("Session integration (scripted peer)", () => { test("no stream data follows STOP_SENDING once connection credit arrives", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams({ initialMaxData: 0n }) }); + await session.ready; const uni = await session.createUnidirectionalStream(); const write = settleTo(uni.getWriter().write(new Uint8Array(10))); @@ -1099,7 +1124,7 @@ describe("Session integration (scripted peer)", () => { test("close() sends APPLICATION_CLOSE, resolves closed, and is idempotent", async () => { const { session, peer } = connect(); - await session.ready; + await started(peer); session.close({ closeCode: 42, reason: "bye" }); expect(await session.closed).toEqual({ closeCode: 42, reason: "bye" }); @@ -1115,7 +1140,7 @@ describe("Session integration (scripted peer)", () => { test("a close before TRANSPORT_PARAMETERS is written still sends them first", async () => { const { session, peer } = connect(); peer.blockWrites(); - await session.ready; + await started(peer); session.close({ closeCode: 42, reason: "bye" }); await settle(); @@ -1138,8 +1163,8 @@ describe("Session integration (scripted peer)", () => { /** Wedge the socket with a write in flight, a stream write and a RESET_STREAM * queued behind it, and return how many chunks reached the wire before. */ async function wedge(session: Session, peer: FakePeer): Promise { - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; await waitFor(() => peer.has("transport_parameters")); const writer = (await session.createUnidirectionalStream()).getWriter(); const aborted = await session.createUnidirectionalStream(); @@ -1193,7 +1218,7 @@ describe("Session integration (scripted peer)", () => { describe("closed settles graceful vs abnormal", () => { test("a peer APPLICATION_CLOSE resolves closed with its code and reason", async () => { const { session, peer } = connect(); - await session.ready; + await started(peer); // The peer closing the session deliberately (APPLICATION_CLOSE / 0x1d) is // graceful, even though we didn't initiate it. @@ -1203,7 +1228,7 @@ describe("Session integration (scripted peer)", () => { test("a peer APPLICATION_CLOSE fulfills even when its code looks like a transport error", async () => { const { session, peer } = connect(); - await session.ready; + await started(peer); // 1002 is a transport-error code, but an APPLICATION_CLOSE is graceful by // definition - the *subtype*, not the code, decides. Codes are @@ -1214,7 +1239,7 @@ describe("Session integration (scripted peer)", () => { test("a peer CONNECTION_CLOSE rejects closed", async () => { const { session, peer } = connect(); - await session.ready; + await started(peer); // The peer detected a protocol violation / transport error and sent a // CONNECTION_CLOSE (0x1c) - abnormal, so `closed` rejects rather than @@ -1230,7 +1255,7 @@ describe("Session integration (scripted peer)", () => { test("a socket drop with no CONNECTION_CLOSE rejects closed", async () => { const { session, peer } = connect(); - await session.ready; + await started(peer); // Even a "clean" WebSocket status code is a drop at the session layer: the // peer never said goodbye in QMux terms. @@ -1242,7 +1267,7 @@ describe("Session integration (scripted peer)", () => { test("a socket error rejects closed, preserving the underlying failure", async () => { const { session, peer } = connect(); - await session.ready; + await started(peer); peer.error(new Error("connection reset")); @@ -1262,7 +1287,7 @@ describe("Session integration (scripted peer)", () => { const installed = clock.install(); try { const { session, peer } = connect({ idleTimeout: 150 }); - await session.ready; + await started(peer); await waitFor(() => peer.has("transport_parameters")); // A successfully written keep-alive is send activity under QMux. Block the // sink so neither inbound nor outbound frames can reset the idle deadline. @@ -1299,7 +1324,7 @@ describe("Session integration (scripted peer)", () => { const installed = clock.install(); try { const { session, peer } = connect({ idleTimeout: 150 }); - await session.ready; + await started(peer); await waitFor(() => peer.has("transport_parameters")); await clock.advance(Nano.fromMilli(Milli(200))); @@ -1316,8 +1341,8 @@ describe("Session integration (scripted peer)", () => { const installed = clock.install(); try { const { session, peer } = connect({ idleTimeout: 120 }); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; const writable = await session.createUnidirectionalStream(); const writer = writable.getWriter(); @@ -1350,8 +1375,8 @@ describe("Session integration (scripted peer)", () => { const installed = clock.install(); try { const { session, peer } = connect({ idleTimeout: 120 }); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; const writable = await session.createUnidirectionalStream(); const writer = writable.getWriter(); @@ -1376,7 +1401,7 @@ describe("Session integration (scripted peer)", () => { // The downstream bug this fixes (moq-dev/moq#2183): code written against the // native API reconnects from the catch arm, which qmux could never reach. const { session, peer } = connect(); - await session.ready; + await started(peer); let reconnected = false; const watch = (async () => { @@ -1396,7 +1421,7 @@ describe("Session integration (scripted peer)", () => { test("a text frame rejects closed and tells the peer why (1003)", async () => { const { session, peer } = connect(); - await session.ready; + await started(peer); peer.sendText("not binary"); const err = await expectSessionFailure(session); @@ -1408,8 +1433,8 @@ describe("Session integration (scripted peer)", () => { test("an oversized WebSocket record rejects closed before frame decoding", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; // An all-zero record is otherwise valid PADDING, so only the negotiated // record-size limit should make this fatal. @@ -1422,7 +1447,7 @@ describe("Session integration (scripted peer)", () => { test("draft-01 rejects max_record_size below the default minimum", async () => { const { session, peer } = connect(); - await session.ready; + await started(peer); peer.send({ type: "transport_parameters", @@ -1439,7 +1464,7 @@ describe("Session integration (scripted peer)", () => { // a RESET_STREAM_AT (0x24) frame is a protocol violation. Hand-built bytes: // type=0x24, id=3, code=0, final_size=0, reliable_size=0. const { session, peer } = connect(); - await session.ready; + await started(peer); peer.sendRaw(new Uint8Array([0x24, 0x03, 0x00, 0x00, 0x00])); const err = await expectSessionFailure(session); @@ -1451,7 +1476,7 @@ describe("Session integration (scripted peer)", () => { test("datagrams: lowering the live high-water mark retains backlog and sheds later overflow", async () => { const { session, peer } = connect(); - await session.ready; + await started(peer); const datagrams = session.datagrams; datagrams.incomingHighWaterMark = 3; for (const value of [1, 2]) peer.send({ type: "datagram", data: new Uint8Array([value]) }); @@ -1474,7 +1499,7 @@ describe("Session integration (scripted peer)", () => { test("datagrams: raising the live high-water mark admits more queued packets", async () => { const { session, peer } = connect(); - await session.ready; + await started(peer); session.datagrams.incomingHighWaterMark = 1; for (const value of [1, 2]) peer.send({ type: "datagram", data: new Uint8Array([value]) }); await peer.barrier(); @@ -1488,8 +1513,8 @@ describe("Session integration (scripted peer)", () => { }); test("datagrams: the live limit validates input without changing the previous policy", async () => { - const { session } = connect(); - await session.ready; + const { session, peer } = connect(); + await started(peer); const datagrams = session.datagrams; for (const value of [0, -0, 0.5, 1.5, Infinity]) { datagrams.incomingHighWaterMark = value; @@ -1512,8 +1537,8 @@ describe("Session integration (scripted peer)", () => { }); test("datagrams: unsupported policies accept only their defaults", async () => { - const { session } = connect(); - await session.ready; + const { session, peer } = connect(); + await started(peer); const datagrams = session.datagrams; for (const [field, defaultValue] of [ ["incomingMaxAge", null], @@ -1537,7 +1562,7 @@ describe("Session integration (scripted peer)", () => { test("datagrams: pending reads bypass the queue and draining frees capacity", async () => { const { session, peer } = connect(); - await session.ready; + await started(peer); session.datagrams.incomingHighWaterMark = 1; const reader = session.datagrams.readable.getReader(); const pending = reader.read(); @@ -1555,7 +1580,7 @@ describe("Session integration (scripted peer)", () => { for (const queued of [false, true]) { test(`datagrams: cancellation clears ${queued ? "queued packets" : "a pending read"} and ignores later arrivals`, async () => { const { session, peer } = connect(); - await session.ready; + await started(peer); session.datagrams.incomingHighWaterMark = 1; if (queued) { peer.send({ type: "datagram", data: new Uint8Array([1]) }); @@ -1576,7 +1601,7 @@ describe("Session integration (scripted peer)", () => { test("datagrams: session failure discards queued packets and rejects reads", async () => { const { session, peer } = connect(); - await session.ready; + await started(peer); session.datagrams.incomingHighWaterMark = 1; peer.send({ type: "datagram", data: new Uint8Array([1]) }); await peer.barrier(); @@ -1586,8 +1611,8 @@ describe("Session integration (scripted peer)", () => { }); test("datagrams: the runtime view has no constructor or transport mutators for applications", async () => { - const { session } = connect(); - await session.ready; + const { session, peer } = connect(); + await started(peer); const datagrams = session.datagrams; expect("Datagrams" in QMux).toBe(false); for (const key of ["push", "close", "setMaxDatagramSize"]) expect(key in datagrams).toBe(false); @@ -1599,8 +1624,8 @@ describe("Session integration (scripted peer)", () => { test("datagrams: an app write produces a DATAGRAM frame on the wire", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; await waitFor(() => session.datagrams.maxDatagramSize > 0); await session.datagrams.writable.getWriter().write(new Uint8Array([1, 2, 3])); @@ -1613,8 +1638,8 @@ describe("Session integration (scripted peer)", () => { test("datagrams: an incoming DATAGRAM frame is delivered to the readable", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; peer.send({ type: "datagram", data: new Uint8Array([9, 8, 7]) }); const { value } = await session.datagrams.readable.getReader().read(); @@ -1624,8 +1649,8 @@ describe("Session integration (scripted peer)", () => { test("native WebSocketStream ArrayBuffer records are normalized before QMux decoding", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; peer.sendArrayBuffer({ type: "datagram", data: new Uint8Array([4, 5, 6]) }); const { value } = await session.datagrams.readable.getReader().read(); @@ -1637,8 +1662,8 @@ describe("Session integration (scripted peer)", () => { // ourParams.maxDatagramFrameSize = 10; an 8-byte payload encodes to a // 1 (type) + 1 (length varint) + 8 = 10-byte frame - exactly the limit. const { session, peer } = connect({ maxDatagramFrameSize: 10n }); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; peer.send({ type: "datagram", data: new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]) }); const { value } = await session.datagrams.readable.getReader().read(); @@ -1651,8 +1676,8 @@ describe("Session integration (scripted peer)", () => { // 1 + 1 + 10 = 12-byte frame > 10 - a peer exceeding the size we negotiated // is a PROTOCOL_VIOLATION (RFC 9221), so the session must close, not drop. const { session, peer } = connect({ maxDatagramFrameSize: 10n }); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; peer.send({ type: "datagram", data: new Uint8Array(10) }); await expectSessionFailure(session); @@ -1663,8 +1688,8 @@ describe("Session integration (scripted peer)", () => { // ourParams.maxDatagramFrameSize = 0 → we advertised no datagram support, so // receiving one at all is a PROTOCOL_VIOLATION (RFC 9221), not a droppable frame. const { session, peer } = connect({ maxDatagramFrameSize: null }); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; peer.send({ type: "datagram", data: new Uint8Array([1, 2, 3]) }); await expectSessionFailure(session); @@ -1677,8 +1702,8 @@ describe("Session integration (scripted peer)", () => { // limit - even though the length-prefixed reconstruction (1 + 1 + 9 = 11) // would wrongly drop it. Hand-build the record: a 0x30 type byte + payload. const { session, peer } = connect({ maxDatagramFrameSize: 10n }); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; const payload = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9]); peer.sendRaw(new Uint8Array([0x30, ...payload])); @@ -1689,7 +1714,7 @@ describe("Session integration (scripted peer)", () => { test("datagrams: maxDatagramSize reflects the peer's advertised frame size", async () => { const { session, peer } = connect(); - await session.ready; + await started(peer); // frame size 1201 → payload 1201 - (1 type byte + 2-byte length varint) = 1198. peer.send({ type: "transport_parameters", params: peerParams({ maxDatagramFrameSize: 1201n }) }); @@ -1700,8 +1725,8 @@ describe("Session integration (scripted peer)", () => { test("datagrams: a peer that disables datagrams leaves maxDatagramSize at 0 and drops writes", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams({ maxDatagramFrameSize: 0n }) }); + await session.ready; // A ping barrier confirms the params have been processed. peer.send({ type: "ping_request", sequence: 1n }); @@ -1719,8 +1744,8 @@ describe("Session integration (scripted peer)", () => { test("datagrams: readable closes cleanly on a graceful session close", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; const reader = session.datagrams.readable.getReader(); session.close(); // graceful: no #closeReason, so the readable must not error @@ -1731,8 +1756,8 @@ describe("Session integration (scripted peer)", () => { test("MAX_STREAM_DATA is extended on delivery to the app, not on receipt", async () => { // Small per-stream window so a few delivered chunks cross the half-window threshold. const { session, peer } = connect({ streamReceiveWindow: 1000n }); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; // Peer opens a server-initiated uni stream and sends 4×200B (=800 ≤ window). const id = Stream.Id.create(0n, Stream.Dir.Uni, true); @@ -1778,8 +1803,8 @@ describe("Session integration (scripted peer)", () => { receiveWindow: 100n, streamReceiveWindow: 100n, }); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; peer.send({ type: "stream", @@ -1813,8 +1838,8 @@ describe("Session integration (scripted peer)", () => { test("accepted active streams do not recycle stream-count credit", async () => { const { session, peer } = connect({ maxStreamsUni: 1n }); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; const id = Stream.Id.create(0n, Stream.Dir.Uni, true); peer.send({ type: "stream", id, data: new Uint8Array([1]), fin: false }); @@ -1838,8 +1863,8 @@ describe("Session integration (scripted peer)", () => { async function accept() { const { session, peer } = connect({ maxStreamsBidi: 1n }); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; peer.send({ type: "stream", id, data: new Uint8Array([1]), fin: false }); const accepted = await session.incomingBidirectionalStreams.getReader().read(); if (accepted.done || !accepted.value) throw new Error("expected an incoming stream"); @@ -1920,8 +1945,8 @@ describe("Session integration (scripted peer)", () => { test("a STREAM frame arriving after close() is dropped without an unhandled rejection", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; session.close({ closeCode: 42, reason: "bye" }); @@ -1955,8 +1980,8 @@ describe("Session integration (scripted peer)", () => { test("a STREAM frame on a send-only stream ID fails the session with 1002", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; // A client-initiated uni stream is send-only from our (client) perspective; // the peer writing to it is a protocol violation. Now that #handleStreamFrame @@ -1977,8 +2002,8 @@ describe("Session integration (scripted peer)", () => { test("a stream arriving after the app cancelled the acceptor is refused, not fatal", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; // App stops accepting incoming uni streams while the session stays open. await session.incomingUnidirectionalStreams.cancel(); @@ -2003,8 +2028,8 @@ describe("Session integration (scripted peer)", () => { test("repeated frames on a refused stream id do not amplify STOP_SENDING or re-credit stream count", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; await session.incomingUnidirectionalStreams.cancel(); @@ -2036,8 +2061,8 @@ describe("Session integration (scripted peer)", () => { // advertised window never replenishes and the peer is wrongly starved / // eventually tripped into a 1002 flow-control close. const { session, peer } = connect({ receiveWindow: 300n }); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; await session.incomingUnidirectionalStreams.cancel(); @@ -2069,8 +2094,8 @@ describe("Session integration (scripted peer)", () => { // passes waitUntilAvailable: false where it relies on that. test("streamCredit counts down per direction and reports a waiting create as blocked", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams({ initialMaxStreamsUni: 1n }) }); + await session.ready; await session.createUnidirectionalStream(); expect(session.streamCredit("uni")).toEqual({ available: 0n, blocked: false }); @@ -2094,8 +2119,8 @@ describe("Session integration (scripted peer)", () => { test("an exhausted uni limit rejects at once, and a later grant is usable", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams({ initialMaxStreamsUni: 1n }) }); + await session.ready; await session.createUnidirectionalStream({ waitUntilAvailable: false }); refused(await settleTo(session.createUnidirectionalStream({ waitUntilAvailable: false }))); @@ -2111,8 +2136,8 @@ describe("Session integration (scripted peer)", () => { test("an exhausted bidi limit rejects at once", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams({ initialMaxStreamsBidi: 0n }) }); + await session.ready; refused(await settleTo(session.createBidirectionalStream({ waitUntilAvailable: false }))); session.close(); @@ -2120,7 +2145,7 @@ describe("Session integration (scripted peer)", () => { test("a create before TRANSPORT_PARAMETERS waits for the peer's limit", async () => { const { session, peer } = connect(); - await session.ready; + await started(peer); const created = session.createUnidirectionalStream({ waitUntilAvailable: false }); await flushMicrotasks(); @@ -2131,8 +2156,8 @@ describe("Session integration (scripted peer)", () => { }); test("a create before TRANSPORT_PARAMETERS rejects with the close reason", async () => { - const { session } = connect(); - await session.ready; + const { session, peer } = connect(); + await started(peer); const created = settleTo(session.createBidirectionalStream({ waitUntilAvailable: false })); await flushMicrotasks(); @@ -2145,7 +2170,7 @@ describe("Session integration (scripted peer)", () => { describe("close threads its reason into blocked Credit.claim() waiters", () => { test("a uni stream blocked on stream-count credit rejects with the graceful close reason", async () => { const { session, peer } = connect(); - await session.ready; + await started(peer); // Peer grants zero uni stream-count credit, so createUnidirectionalStream parks on claim(). peer.send({ type: "transport_parameters", params: peerParams({ initialMaxStreamsUni: 0n }) }); peer.send({ type: "ping_request", sequence: 1n }); @@ -2163,8 +2188,8 @@ describe("Session integration (scripted peer)", () => { test("a bidi stream blocked on stream-count credit rejects with a CONNECTION_CLOSE frame's reason", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams({ initialMaxStreamsBidi: 0n }) }); + await session.ready; peer.send({ type: "ping_request", sequence: 1n }); await waitFor(() => peer.has("ping_response")); @@ -2183,8 +2208,8 @@ describe("Session integration (scripted peer)", () => { test("a stream write blocked on send credit rejects with the close reason", async () => { // Tiny per-stream send window: the first chunk drains it, the next write parks. const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams({ initialMaxStreamDataUni: 5n }) }); + await session.ready; const writable = await session.createUnidirectionalStream(); const writer = writable.getWriter(); @@ -2202,8 +2227,8 @@ describe("Session integration (scripted peer)", () => { test("a blocked claim rejects with the reason from a WebSocket-level close", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams({ initialMaxStreamsUni: 0n }) }); + await session.ready; peer.send({ type: "ping_request", sequence: 1n }); await waitFor(() => peer.has("ping_response")); @@ -2220,8 +2245,8 @@ describe("Session integration (scripted peer)", () => { }); test("createBidirectionalStream on an already-closed session rejects with the descriptive reason", async () => { - const { session } = connect(); - await session.ready; + const { session, peer } = connect(); + await started(peer); // Graceful app-initiated close leaves #closeReason unset, so the synchronous // already-closed throw must fall back to #closed's "Connection closed: ", @@ -2268,8 +2293,8 @@ describe("Session.accept (server role)", () => { // The whole point of the role: a server minting client-initiated ids would // collide with the client's own streams. const { session, peer } = accept(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; const writable = await session.createUnidirectionalStream(); await writable.getWriter().write(new Uint8Array([1])); @@ -2282,8 +2307,8 @@ describe("Session.accept (server role)", () => { test("bidi streams we open are server-initiated", async () => { const { session, peer } = accept(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; const stream = await session.createBidirectionalStream(); await stream.writable.getWriter().write(new Uint8Array([1])); @@ -2296,8 +2321,8 @@ describe("Session.accept (server role)", () => { test("a client-initiated stream arrives as an incoming stream", async () => { const { session, peer } = accept(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; // Client-initiated (isServer: false) - the mirror of what a client session // accepts, and what a client session would reject as a violation. @@ -2318,8 +2343,8 @@ describe("Session.accept (server role)", () => { test("a peer using our own role's stream ids is a protocol violation", async () => { const { session, peer } = accept(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; // Only the server may open server-initiated uni streams; a client sending // one is either confused or spoofing our side of the id space. @@ -2342,7 +2367,7 @@ describe("Session.accept (server role)", () => { // "Expected ArrayBuffer for the first argument" out of the varint decoder // and the session never opens a stream. const { session, peer } = accept(); - await session.ready; + await started(peer); peer.sendArrayBuffer({ type: "transport_parameters", params: peerParams() }); // Decoding the params is what grants the stream-count credit this claims. @@ -2354,7 +2379,7 @@ describe("Session.accept (server role)", () => { test("the wire format comes from the socket's negotiated subprotocol", async () => { const { session, peer } = accept({ protocol: "qmux-01.moq-lite-04" }); - await session.ready; + await started(peer); expect(session.protocol).toBe("moq-lite-04"); // A QMux draft was negotiated, so we owe the peer our parameters. await waitFor(() => peer.has("transport_parameters")); @@ -2368,7 +2393,7 @@ describe("Session.accept (server role)", () => { config: { idleTimeout: null }, protocol: "qmux-01.moq-lite-04", }); - await session.ready; + await started(peer); expect(session.protocol).toBe("moq-lite-04"); await waitFor(() => peer.has("transport_parameters")); session.close(); @@ -2378,7 +2403,6 @@ describe("Session.accept (server role)", () => { // What Deno.upgradeWebSocket / `ws` actually hand back. const ws = new FakeServerSocket("wss://example/test", "qmux-01"); const session = Session.accept(ws, { config: { idleTimeout: null } }); - await session.ready; await waitFor(() => ws.sent.length > 0); const [params] = Frame.decodeRecord(ws.sent[0] as Uint8Array); @@ -2425,8 +2449,8 @@ describe("STREAM frame size", () => { // handshake invited. A peer chunking at any other header budget - an older // release, a third-party stack - lands somewhere in this range too. const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; const id = Stream.Id.create(0n, Stream.Dir.Uni, true); const data = new Uint8Array(Number(DEFAULT_MAX_RECORD_SIZE) - 5).fill(0x5a); @@ -2438,11 +2462,33 @@ describe("STREAM frame size", () => { session.close(); }); + test("a qmux-00 peer that never sends its parameters fails ready at the handshake deadline", async () => { + // qmux-00 has no idle timer, so only the handshake deadline bounds `ready`. + const clock = new Manual(); + const installed = clock.install(); + try { + const { session, peer } = accept({ protocol: "qmux-00", config: { handshakeTimeout: 150 } }); + await started(peer); + const ready = settleTo(session.ready); + + await clock.advance(Nano.fromMilli(Milli(150))); + await settle(); + expect(peer.has("connection_close")).toBe(false); + await clock.advance(Nano.fromMilli(Milli(50))); + + const err = await expectSessionFailure(session); + expect(err.message).toContain("handshake timeout"); + expect(await ready).toBeInstanceOf(Error); + } finally { + installed.close(); + } + }); + test("qmux-00 delivers a frame of exactly max_frame_size", async () => { // draft-00 §5.2 bounds the whole frame, header included, so a 16384-byte // frame is legal - and the parameter may only ever be raised. const { session, peer } = accept({ protocol: "qmux-00" }); - await session.ready; + await started(peer); const id = Stream.Id.create(0n, Stream.Dir.Uni, false); const data = new Uint8Array(Frame.MAX_FRAME_SIZE - 5).fill(0x5a); @@ -2458,7 +2504,7 @@ describe("STREAM frame size", () => { // One byte past the limit is a frame-size violation, which draft-00 §5.2 // requires closing the connection over. const { session, peer } = accept({ protocol: "qmux-00" }); - await session.ready; + await started(peer); const id = Stream.Id.create(0n, Stream.Dir.Uni, false); const data = new Uint8Array(Frame.MAX_FRAME_SIZE - 4).fill(0x5a); @@ -2477,8 +2523,8 @@ describe("STREAM frame size", () => { // it is the one worth enforcing - and a record too large to parse is a // connection-level violation. const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; peer.sendRaw(new Uint8Array(Number(DEFAULT_MAX_RECORD_SIZE) + 1)); @@ -2490,8 +2536,8 @@ describe("STREAM frame size", () => { test("we keep STREAM payloads within the released-receiver ceiling", async () => { const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; const writable = await session.createUnidirectionalStream(); await writable.getWriter().write(new Uint8Array(Number(DEFAULT_MAX_RECORD_SIZE) * 2).fill(0x5a)); @@ -2506,8 +2552,8 @@ describe("STREAM frame size", () => { // max_record_size is a varint, so 2^62-1 is legal - and is not a value // `number` holds exactly, so the budget has to stay a bigint. const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams({ maxRecordSize: VarInt.MAX }) }); + await session.ready; const writable = await session.createUnidirectionalStream(); const data = new Uint8Array(1024).fill(0x5a); @@ -2522,8 +2568,8 @@ describe("STREAM frame size", () => { test("a larger peer record limit does not bypass the compatibility ceiling", async () => { const maxRecordSize = 32_768n; const { session, peer } = connect(); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams({ maxRecordSize }) }); + await session.ready; const writable = await session.createUnidirectionalStream(); await writable.getWriter().write(new Uint8Array(Number(maxRecordSize) * 2).fill(0x5a)); @@ -2550,8 +2596,8 @@ describe("RESET_STREAM_AT (qmux-02)", () => { /** A qmux-02 server session with one client-initiated uni stream carrying `chunks`. */ async function open(chunks: number[][], config?: Config) { const { session, peer } = accept({ protocol: "qmux-02", config }); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; const id = Stream.Id.create(0n, Stream.Dir.Uni, false); let offset = 0n; @@ -2623,8 +2669,8 @@ describe("RESET_STREAM_AT (qmux-02)", () => { test("a refused stream's reliable prefix still returns connection credit", async () => { const { session, peer } = accept({ protocol: "qmux-02", config: { receiveWindow: 10n } }); - await session.ready; peer.send({ type: "transport_parameters", params: peerParams() }); + await session.ready; const id = Stream.Id.create(0n, Stream.Dir.Uni, false); peer.send({ type: "stream", id, offset: 0n, data: new Uint8Array(10), fin: false }); diff --git a/js/qmux/src/session.ts b/js/qmux/src/session.ts index b5b13ec17d9..42b5f5aab9d 100644 --- a/js/qmux/src/session.ts +++ b/js/qmux/src/session.ts @@ -1,4 +1,15 @@ -import { Instant, type Interval, interval, Milli, MissedTickBehavior, Nano, now, Second, timeout } from "@moq/clock"; +import { + Elapsed, + Instant, + type Interval, + interval, + Milli, + MissedTickBehavior, + Nano, + now, + Second, + timeout, +} from "@moq/clock"; import { Credit, replenishWindow } from "./credit.ts"; import { resetCode, SessionError, StreamError, streamCode } from "./error.ts"; import type { TransportParams, WireFormat } from "./frame.ts"; @@ -37,6 +48,9 @@ export interface Config { streamReceiveWindow?: bigint; /** Idle timeout in milliseconds, or null to disable it; zero is refused. */ idleTimeout?: number | null; + /** How long `ready` waits for the peer's transport parameters, in milliseconds, or null to wait + * indefinitely; zero is refused. The session closes when it passes. */ + handshakeTimeout?: number | null; /** Maximum QMux Record size in bytes (draft-01). */ maxRecordSize?: bigint; /** Largest DATAGRAM *frame* (RFC 9221: type + length + payload) we advertise @@ -54,6 +68,7 @@ const DEFAULT_CONFIG: Required = { receiveWindow: 1_048_576n, streamReceiveWindow: 262_144n, idleTimeout: 30_000, + handshakeTimeout: 10_000, maxRecordSize: Frame.DEFAULT_MAX_RECORD_SIZE, // Fill a full record by default; the record layer bounds the size. maxDatagramFrameSize: Frame.DEFAULT_MAX_RECORD_SIZE, @@ -72,9 +87,9 @@ function resolveConfig(config?: Config): Required { if (value !== undefined) Object.assign(resolved, { [key]: value }); } for (const [key, value] of Object.entries(resolved)) { - if (key === "idleTimeout") { + if (key === "idleTimeout" || key === "handshakeTimeout") { if (value !== null && (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0)) { - throw new TypeError("idleTimeout must be a positive safe integer or null"); + throw new TypeError(`${key} must be a positive safe integer or null`); } } else if (key !== "maxDatagramFrameSize" || value !== null) { if (typeof value !== "bigint") throw new TypeError(`${key} must be a bigint`); @@ -660,7 +675,8 @@ export default class Session implements WebTransport { return this.#protocol; } - /** Resolves once the WebSocket opens and the session can carry streams. */ + /** Resolves once the peer's transport parameters arrive, as a WebTransport handshake completes: + * stream limits and `datagrams.maxDatagramSize` are known from then on. */ readonly ready: Promise; #readyResolve: () => void; #readyReject: (err: Error) => void; @@ -956,11 +972,19 @@ export default class Session implements WebTransport { this.#bidiStreamCredit = new Credit(0n); this.#uniStreamCredit = new Credit(0n); this.#recvDataMax = this.#ourParams.initialMaxData; - // Our own deadline applies until the peer's parameters arrive, so a peer - // that never sends them can't hold the session open. + // Our own idle deadline applies until the peer's parameters arrive. this.#startIdleTimerIfEnabled(); - - this.#readyResolve(); + // The handshake deadline also covers qmux-00 and a disabled idle timeout, so + // a peer that never sends its parameters can't hold `ready` forever. + const handshake = this.#config.handshakeTimeout; + if (handshake !== null) { + timeout(Nano.fromMilli(Milli(handshake)), this.ready).catch((err) => { + if (!(err instanceof Elapsed)) return; + this.#closeReason ??= new Error("handshake timeout"); + this.#abort(0, "handshake timeout"); + this.#transportClose(); + }); + } } #onData(data: Uint8Array) { @@ -1136,6 +1160,7 @@ export default class Session implements WebTransport { // The peer's limit may be shorter than ours. this.#startIdleTimerIfEnabled(); + this.#readyResolve(); } /** Effective idle timeout in ms, or 0 if disabled. diff --git a/js/qmux/src/web-socket-stream.test.ts b/js/qmux/src/web-socket-stream.test.ts index 23ea5e2d6f5..8e108efa05e 100644 --- a/js/qmux/src/web-socket-stream.test.ts +++ b/js/qmux/src/web-socket-stream.test.ts @@ -34,6 +34,7 @@ class FakeWebSocket implements WebSocketLike { send(data: string | ArrayBufferLike | ArrayBufferView): void { this.sent.push(data); + this.bufferedAmount += typeof data === "string" ? data.length : data.byteLength; } close(code?: number, reason?: string): void { this.closeArgs = { code, reason }; @@ -121,6 +122,27 @@ describe("WebSocketStream ponyfill", () => { expect(settled).toBe(true); }); + test("only a backlog past the mark is backpressure, not a write in flight", async () => { + const wss = new WebSocketStream("wss://x", { webSocket: ctor, highWaterMark: 100 }); + const ws = FakeWebSocket.last as FakeWebSocket; + ws.open(); + const { writable } = await wss.opened; + const writer = writable.getWriter(); + + // A write in flight under the mark leaves room, so a datagram behind it still goes. + const writes = [writer.write(new Uint8Array(40))]; + expect(writer.desiredSize).toBeGreaterThan(0); + // A burst counts the bytes still queued behind it with what the socket buffers. + writes.push(writer.write(new Uint8Array(40))); + expect(writer.desiredSize).toBeGreaterThan(0); + writes.push(writer.write(new Uint8Array(40))); + expect(writer.desiredSize).toBe(0); + + ws.bufferedAmount = 0; + await Promise.all(writes); + expect(writer.desiredSize).toBeGreaterThan(0); + }); + test("setHighWaterMark resizes backpressure live (mid-drain)", async () => { const wss = new WebSocketStream("wss://x", { webSocket: ctor, highWaterMark: 100 }); const ws = FakeWebSocket.last as FakeWebSocket; diff --git a/js/qmux/src/web-socket-stream.ts b/js/qmux/src/web-socket-stream.ts index 7d5505bfb2f..b02520968d9 100644 --- a/js/qmux/src/web-socket-stream.ts +++ b/js/qmux/src/web-socket-stream.ts @@ -144,7 +144,7 @@ function validCloseCode(code: number | undefined): code is number { * The mark is read live via `highWaterMark()` on every check, so a runtime * resize (see {@link WebSocketStream.setHighWaterMark}) takes effect mid-drain. * Returns `undefined` synchronously when there's already room - no microtask - * on the hot path, so `writer.ready` stays resolved when the socket is keeping up. */ + * on the hot path. */ function drain(ws: WebSocketLike, highWaterMark: () => number): Promise | undefined { if (ws.bufferedAmount <= highWaterMark()) return undefined; return (async () => { @@ -157,6 +157,11 @@ function drain(ws: WebSocketLike, highWaterMark: () => number): Promise | })(); } +/** The bytes `chunk` adds to `bufferedAmount`. */ +function byteLength(chunk: WebSocketStreamData): number { + return typeof chunk === "string" ? new TextEncoder().encode(chunk).byteLength : chunk.byteLength; +} + /** A `WebSocketStream` implemented over a plain `WebSocket`. */ export class WebSocketStream implements WebSocketStreamLike { readonly url: string; @@ -198,16 +203,37 @@ export class WebSocketStream implements WebSocketStreamLike { cancel: () => ws.close(), }); - const writable = new WritableStream({ - write: (chunk) => { - ws.send(chunk); - return drain(ws, () => this.#highWaterMark); + // Bytes written to the writable but not yet handed to the socket, and each queued + // chunk's size as measured on entry, since a resizable buffer can change it later. + let queued = 0; + const sizes: number[] = []; + const writable = new WritableStream( + { + write: (chunk) => { + queued -= sizes.shift() ?? 0; + ws.send(chunk); + return drain(ws, () => this.#highWaterMark); + }, + // A WebSocket has no half-close, so closing/aborting the writable closes + // the whole socket. Without this, `writer.close()` would leave it open. + close: () => ws.close(), + abort: () => ws.close(), }, - // A WebSocket has no half-close, so closing/aborting the writable closes - // the whole socket. Without this, `writer.close()` would leave it open. - close: () => ws.close(), - abort: () => ws.close(), - }); + { + // A chunk counts only when it takes the backlog past the mark, so `desiredSize` + // reaches 0 only once the socket is behind. Counting every chunk would report + // backpressure for each write in flight, however small the backlog. + highWaterMark: 1, + // The DOM typing admits `undefined`, which a WebSocket can't send. + size: (chunk) => { + if (chunk === undefined) throw new TypeError("WebSocketStream cannot send undefined"); + const size = byteLength(chunk); + sizes.push(size); + queued += size; + return ws.bufferedAmount + queued > this.#highWaterMark ? 1 : 0; + }, + }, + ); ws.onopen = () => { opened.resolve({ readable, writable, extensions: ws.extensions, protocol: ws.protocol }); diff --git a/quest/m1/README.md b/quest/m1/README.md index c772a56bdbb..011bd84b7d1 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -25,7 +25,7 @@ because a downstream iGPU transcode trial needs it now. Held here by open claims: a quest's branch is its path, so a claimed quest cannot move until its PR merges, and an epic moves with its children. These breaking epics and quests stay in m1 for now and are listed in m2's -`Required`, so the cut still waits on them: api-audit, datagram-tracks, drop-set, rind, session-policy, and +`Required`, so the cut still waits on them: api-audit, drop-set, rind, session-policy, and stream-credit. The [re-cut follow-up](/quest/m2/recut-held.md) moves what remains of them once their claims merge. @@ -39,7 +39,6 @@ moves what remains of them once their claims merge. - [Group errors are cached by kind](/quest/m1/group-error-cache.md) - permanent group errors bind every reader, retryable ones are kept only for a bounded time, and a live SUBSCRIBE_DROP or FETCH answered `Old` no longer caches it for good - [A route answer behind its idle copy's cache fails the copy](/quest/m1/answer-behind-cache.md) - a resuming copy whose route answers behind its cache fails loud instead of refusing the feed's groups as duplicates, so readers resubscribe onto a fresh copy - [The overcommitted receive-window cells run again](/quest/m1/receive-windows-evicted.md) - `benchmark_receive_windows` measures its 256-stream and 4 MiB-frame cells again, reporting delivered frames and evictions instead of stalling -- [Datagram tracks](/quest/m1/datagram-tracks/README.md) - a track is datagrams or streams; datagram tracks have their own request and sequence, no ranges, no cache, and map to object ID 0 on moq-transport - [Stream credit by priority](/quest/m1/stream-credit/README.md) - every stream opens through one priority entry point, and a higher-priority group takes over or resets a lower one when credit runs out - [Audio jitter target](/quest/m1/audio-jitter-target/README.md) - the playout target is default in both languages; time-stretched browser playback without steady-state underruns and a native trace replay remain - [Container reads drop backfill](/quest/m1/read-backfill.md) - the JS container consumer drops groups below its read cursor like Rust diff --git a/quest/m1/datagram-tracks/README.md b/quest/m1/datagram-tracks/README.md deleted file mode 100644 index 3b4e7c8f90b..00000000000 --- a/quest/m1/datagram-tracks/README.md +++ /dev/null @@ -1,127 +0,0 @@ -# [S] Datagram tracks - -## Goal - -A track is either a datagram track or a stream track, fixed when it is -created. A datagram track: - -- is subscribed through its own request, not SUBSCRIBE; -- carries frames that have only a sequence number and a timestamp, with no - group; -- takes no bounded ranges; -- is never cached, stored, or returned by FETCH. - -moq-transport maps its sequence to a group ID with object ID 0. Rust and JS -speak it on lite-07, and the epic ends with a Rust-JS interop test of a -datagram track on lite-07, direct and through a relay. Older lite versions -keep today's datagrams. - -## Plan - -Decided 2026-11-01 (maintainer, in `/quest-plan`): - -- **Datagrams are a track-level decision.** ✅ A track is datagrams or - streams, never a mix. This reverses the - [subscribe-ranges](/quest/m2/subscribe-ranges/README.md) decision of - 2026-10-20 that any single-frame group may go as a datagram, including a - copy of a streamed one. With no mixing, the stream/datagram dedup rule, the - ordering of a datagram among its group's streams, NOT_FETCHABLE, and every - datagram case in range accounting all go from lite-07. - - Reason: datagrams are never cached or stored, so they can't take part in - ranges, fills, or FETCH. Mixing them into a stream track makes every one - of those rules carry a datagram exception. -- **Own request.** ✅ A datagram track is subscribed through its own lite-07 - request, not SUBSCRIBE, and that request carries only a priority. ✅ It is - live from now: no start, end, order, or `Delay`. An update changes only - the priority. A datagram still waits behind higher-priority traffic. -- **No group terminology.** ✅ A datagram carries a sequence number and a - timestamp, with no group. The sequence is the datagram track's own, not - the group sequence space. On moq-transport it maps to a group ID with - object ID 0. - - This exempts datagrams from - [lite-07 by start](/quest/m2/time-addressing/lite07.md): they keep a - sequence, while stream tracks address groups by start. - - The timestamp stays, as it does for every frame. -- **Discovery.** ✅ The application knows which kind a track is, through its - catalog or by convention. The wire carries no kind signal. - - ✅ Datagram tracks and stream tracks have separate namespaces, so - "video" as streams and "video" as datagrams are independent tracks. - - A datagram request for a name with no datagram track is answered as for - any missing track. - - A relay forwards the kind it receives and needs no catalog. -- **Model API.** ✅ Separate types in Rust and JS. A broadcast creates a - stream track or a datagram producer/consumer pair with its own sequence - counter. The datagram types have no group, frame, range, fetch, or cache - API, so the group terminology disappears for datagrams. -- **moq-transport mixing.** ✅ Keep the requested kind. - - One upstream IETF SUBSCRIBE serves both kinds of a name, as on lite-05/06. - Decided 2026-11-05 (maintainer), on - [moq-dev/moq#7959](https://github.com/moq-dev/moq/pull/7959). - - Stream consumers receive only stream objects; datagram consumers receive - only datagrams with object ID 0. A relay forwards both kinds independently. - - Outbound, a datagram track sends only OBJECT_DATAGRAM with object ID 0. -- **Archive.** ✅ moq-archive skips datagram tracks. A datagram track is - live-only, and an archive's playback doesn't include it. -- **Old versions carry both kinds.** ✅ Decided 2026-11-03 (maintainer, on - [moq-dev/moq#7752](https://github.com/moq-dev/moq/pull/7752)): "carry both - on old versions, like moq-transport. Ignore duplicates because in practice, - only one was being used anyway." - - A lite-05/06 SUBSCRIBE for a name carries its stream track's groups and - its datagram track's datagrams, as one moq-transport subscription does. A - name with only a datagram track is served from it alone. - - A subscriber keeps the kind it asked for. One upstream SUBSCRIBE serves - readers of both kinds: the stream track's subscription feeds the name's - datagram track, so a relay between old peers carries datagrams without a - second subscription. - - No dedup: a name using both kinds can deliver a datagram to an old - subscriber that also holds a group of the same sequence. - - Reason: lite-05/06 are the default connections, and moq-ffi/moq-c publish - every raw track's datagrams beside it, so serving a name only one kind - stopped their datagrams on the default path. -- **Old-version lookup.** ✅ Decided 2026-11-04 (maintainer, for - [moq-dev/moq#7847](https://github.com/moq-dev/moq/pull/7847)): change - Rust's lite-05/06 on-demand lookup to discover datagrams without waiting - for a stream-handler answer, keeping the independent binding request API. - Not chosen: requiring stream handlers to reject missing names, with a - not-found rejection added to the bindings. - - A published stream track still serves the name, with its datagram track - beside it. Otherwise a local datagram track answers as soon as its - handler does. Of a name whose two kinds are both requested on demand, - the first answer serves it. - - A session's broadcast is asked for datagrams only once its stream track - is not found: an old session answers a datagram request by subscribing to - the stream track, which a fetch-only or query-only relay must not do. - - Reason: a stream handler need not answer a name it doesn't serve, and - the bindings' rejection carries only an application error. -- **Version.** ✅ lite-07, before it is finalized. - [Finalize moq-lite-07](/quest/m2/lite07-finalize.md) requires this epic. - lite-01..06 keep today's group datagrams. - -Decided by the Rust child ([moq-dev/moq#7752](https://github.com/moq-dev/moq/pull/7752)), -not the maintainer, so open to revisiting: - -- **The answer.** The lite-07 request (Datagrams Stream 0x9: DATAGRAMS, then - DATAGRAMS_UPDATE) is answered with DATAGRAMS_INFO, carrying the publisher - priority and the timescale, and no compression: a datagram track is never - compressed. Why: a subscriber needs the timescale to read a datagram (its - Timestamp is present only on a timed track), so the answer must carry it, - and a separate TRACK lookup would need a kind signal TRACK does not have. A - payload under 1200 bytes, compressed alone with a fresh window, saves little, - while compression would cost every datagram an Inflated Size and a decoder. -- **Timestamp on a `Timescale` 0 track.** The datagram carries none, and its - Sequence stands in for its time. Why: it mirrors the - [model](/quest/m2/time-addressing/model.md)'s rule that a scale-less frame's - timestamp is its group's key, since a datagram's address is its sequence. - Until that model lands, Rust's datagram writes take `Option` like - frame writes do (`None` on an untimed track), and the model quest converts - both. - -This README owns the work no child owns: the Rust-JS interop test of a -datagram track on lite-07, direct and through a relay. - -## Related - -- [Subscribe ranges](/quest/m2/subscribe-ranges/README.md) - ranges no longer cover datagrams -- [Address groups by timestamp](/quest/m2/time-addressing/README.md) - stream tracks address by start; datagram tracks keep a sequence -- [Wrapper traits over moq-net](/quest/m5/net-wrap/README.md) - the traits mirror the separate datagram types -- [moq-lite session tails count drops](/quest/m3/lite-tail-drop-count.md) - datagram holes matter only on lite-05/06 diff --git a/quest/m2/README.md b/quest/m2/README.md index bbcb7530f43..01e3be1c44f 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -179,7 +179,6 @@ quests that require them. - [Cluster routing](/quest/m2/cluster-routing/README.md) - prove shared routing contracts, implement per-origin routes, and connect outbound local clusters - [A job's exact route continues its claim's readers](/quest/m2/announce-takeover.md) - a job's route inherits its claim's instance, replacing the ANNOUNCE_TAKEOVER predecessor design - [A group a subscriber gives up on is always reported](/quest/m2/group-drops.md) - the wire names every abandoned group and the drop signal is public, so readers count losses instead of stalling -- [Datagram tracks](/quest/m1/datagram-tracks/README.md) - a track is datagrams or streams; datagram tracks have their own request and sequence, no ranges, no cache, and map to object ID 0 on moq-transport (held in m1 by an open claim) - [Stream credit by priority](/quest/m1/stream-credit/README.md) - every stream opens through one priority entry point, and a higher-priority group takes over or resets a lower one when credit runs out (held in m1 by an open claim) - [Finalize moq-lite-07](/quest/m2/lite07-finalize.md) - when the maintainer cuts it, lite-07 negotiates as `moq-lite-07` and the next release ships it - [Unbounded groups](/quest/m2/unbounded-groups/README.md) - groups and frames lose their size caps; a group keeps a 32 MB tail, and readers behind it replay through paced flights or refresh diff --git a/quest/m2/lite07-finalize.md b/quest/m2/lite07-finalize.md index ead69e3533b..e1064d24f5c 100644 --- a/quest/m2/lite07-finalize.md +++ b/quest/m2/lite07-finalize.md @@ -116,7 +116,6 @@ timestamp bound in [#6168](https://github.com/moq-dev/moq/pull/6168). - [@moq/net by start](/quest/m2/time-addressing/js.md) - JS speaks the same lite-07 wire - [A job's exact route continues its claim's readers](/quest/m2/announce-takeover.md) - the job's route inherits the claim's instance, with no new wire message - [Takeover](/quest/m1/stream-credit/takeover.md) - lite-07 lets a group stream take over for another group -- [Datagram tracks](/quest/m1/datagram-tracks/README.md) - lite-07 subscribes to datagram tracks through their own request, and datagrams carry their own sequence ## Related diff --git a/quest/m2/recut-held.md b/quest/m2/recut-held.md index 5dee6ce812c..8659a8a79a9 100644 --- a/quest/m2/recut-held.md +++ b/quest/m2/recut-held.md @@ -4,7 +4,7 @@ The epics that open claims held in place during the 2026-11-05 milestone re-cut sit where the re-cut's rules put them. What remains of api-audit, -datagram-tracks, drop-set, rind, +drop-set, rind, session-policy, and stream-credit moves from m1 to m2; and the probe epic moves from m2 to m3. The "held" notes in the m1, m2, and cut gate READMEs are removed, along with each held entry's extra link from m2's or @@ -24,8 +24,7 @@ Drop-set is a single quest, not an epic, so it has no `Required` entry here: when this runs, move it if it still exists and nothing claims it. Prose that names a held epic's milestone becomes stale when it moves; update -it in the same PR: datagram tracks in [net-wrap](/quest/m5/net-wrap/README.md). The browser -padding probes already moved to m3 on 2026-11-06. +it in the same PR. The browser padding probes already moved to m3 on 2026-11-06. ## Required diff --git a/quest/m2/subscribe-ranges/README.md b/quest/m2/subscribe-ranges/README.md index 5fa1803948b..05c06949bc1 100644 --- a/quest/m2/subscribe-ranges/README.md +++ b/quest/m2/subscribe-ranges/README.md @@ -32,7 +32,7 @@ relay bounds a sparse FETCH only if the model can request ranges: replacing its removal); published versions keep it, answered through the same model. - **Holes.** SUBSCRIBE_DROP (restored in lite-07) names every sequence in the requested ranges the publisher won't deliver: never existed, expired, or - refused upstream. On lite-01..06 datagram groups are always dropped in a past range (#4982); on lite-07 ranges never cover datagrams ([Datagram tracks](/quest/m1/datagram-tracks/README.md)). The + refused upstream. On lite-01..06 datagram groups are always dropped in a past range (#4982); on lite-07 ranges never cover datagrams, which have their own track kind. The publisher delivers what it has and fills the rest as upstream answers. - **Model.** `Subscription` gains `ranges` beside its `order`, mirroring the wire; `request_groups` as a separate API was rejected. A publisher's @@ -86,8 +86,7 @@ relay bounds a sparse FETCH only if the model can request ranges: premise that ranges are group-only because a group's timestamp isn't always known: timed tracks know it, and untimed ones refuse. The cache half landed in its own PR after #5929. A datagram was judged on its own (maintainer, 2026-10-20). Superseded - 2026-11-01 (maintainer): datagrams become their own track kind - ([Datagram tracks](/quest/m1/datagram-tracks/README.md)), so on lite-07 + 2026-11-01 (maintainer): datagrams become their own track kind, so on lite-07 a range never covers a datagram. - Ranges are whole groups: a range always starts at a group's first frame (maintainer, on [moq-dev/moq#6465](https://github.com/moq-dev/moq/pull/6465)). The IETF joining FETCH for the diff --git a/quest/m2/time-addressing/lite07.md b/quest/m2/time-addressing/lite07.md index 9f61909bb84..327d45e86d3 100644 --- a/quest/m2/time-addressing/lite07.md +++ b/quest/m2/time-addressing/lite07.md @@ -4,7 +4,7 @@ moq-lite-07 carries no group sequence numbers: a GROUP names its start and its predecessor's start, GROUP_END says where a whole group ends, and every -subscription bound and drop is a time. Datagrams keep a sequence of their own ([Datagram tracks](/quest/m1/datagram-tracks/README.md)). Rust speaks it, the lite +subscription bound and drop is a time. Datagrams keep a sequence of their own on their own track kind. Rust speaks it, the lite draft specifies it, and lite-01..06 are unchanged. ## Plan diff --git a/quest/m2/time-addressing/model.md b/quest/m2/time-addressing/model.md index d1f818bb25d..7461790708b 100644 --- a/quest/m2/time-addressing/model.md +++ b/quest/m2/time-addressing/model.md @@ -77,7 +77,7 @@ it: - Resume across route flips (`resume.rs`), mid-group `Position` and `frame_start`, priority order within a subscription, `Demand::wanted`, and refresh. -- Not datagrams: they become their own track kind with their own sequence ([Datagram tracks](/quest/m1/datagram-tracks/README.md)). +- Not datagrams: they are their own track kind with their own sequence. - The legacy codecs: lite GROUP, SUBSCRIBE and SUBSCRIBE_UPDATE bounds, SUBSCRIBE_START and its largest, SUBSCRIBE_END, SUBSCRIBE_DROP, FETCH, and every IETF Location, Filter, FETCH, Largest, and NEW_GROUP_REQUEST. diff --git a/quest/m3/lite-tail-drop-count.md b/quest/m3/lite-tail-drop-count.md index 0ec7946a4d7..0b3e7f1f056 100644 --- a/quest/m3/lite-tail-drop-count.md +++ b/quest/m3/lite-tail-drop-count.md @@ -9,7 +9,7 @@ From lite-05 on, a moq-lite session's tail is complete once every group up to th Decided 2026-10-30 (maintainer, follow-up planning): m2. Found by the audit on [moq-dev/moq#7403](https://github.com/moq-dev/moq/pull/7403). The maintainer dislikes grace periods. - Count per version. lite-01..04 have no drop message, so they keep today's behaviour. -- On lite-05/06, account for holes left by lost datagrams. Lite-07 stream tracks carry no datagrams ([Datagram tracks](/quest/m1/datagram-tracks/README.md)). +- On lite-05/06, account for holes left by lost datagrams. Lite-07 stream tracks carry no datagrams, which have their own track kind. - Guard against a peer that never accounts for a group: decide with the maintainer whether that ends the tail with an error or keeps waiting. Don't add a new grace. - The IETF tail keeps its grace until the moq-transport gap-signal extension (planned in [moq-dev/moq#7425](https://github.com/moq-dev/moq/pull/7425)) lands, since moq-transport can't signal gaps. diff --git a/quest/m5/net-wrap/README.md b/quest/m5/net-wrap/README.md index be5fc435e1e..4b53f33338c 100644 --- a/quest/m5/net-wrap/README.md +++ b/quest/m5/net-wrap/README.md @@ -33,18 +33,18 @@ and its trait-versus-bridge comparison: - **Mirror moq-net's current API exactly.** The trait methods are the methods writers and readers call today, with the same names, arguments, and errors: `create_track`, `reserve_track`, `requests`, `demand`, - `create_group(group::Info)`, `append_group`, `append_datagram`, - `insert_datagram`, `write_frame`, `create_frame`, `write`, `finish`, - `abort(self, Error)`, `closed`, `track(name)` then `.subscribe(..)`, - `recv_group`, `recv_datagram`, `read_frame`, `next_frame`, `read_chunk`, + `create_group(group::Info)`, `append_group`, `write_frame`, + `create_frame`, `write`, `finish`, `abort(self, Error)`, `closed`, + `track(name)` then `.subscribe(..)`, `recv_group`, `read_frame`, + `next_frame`, `read_chunk`, the broadcast consumer's `tracks` listing (maintainer, 2026-10-24), and their `poll_*` forms. A wrapper adapts to moq-net, not the other way around: `moq_crypto::e2ee::Error` converts into `moq_net::Error`. -- **Datagrams follow the datagram types.** [Datagram tracks](/quest/m1/datagram-tracks/README.md) (m1) replaces - `append_datagram`, `insert_datagram`, and `recv_datagram` on stream tracks - with separate datagram producer and consumer types, so the traits mirror - those types instead. +- **Datagrams follow the datagram types.** Datagram tracks have their own + producer and consumer types (`datagram::Producer::append` and `insert`, + `datagram::Consumer::poll_info` and `poll_recv`), so the traits mirror + those types rather than stream tracks. - **Terminal propagation crosses the wrapper.** Finish, typed aborts (such as e2ee's authentication error), and handle teardown reach the other side at every level, rather than collapsing into `Error::Dropped` or keeping a diff --git a/quest/m5/net-wrap/e2ee.md b/quest/m5/net-wrap/e2ee.md index db276b01bdb..a6b369ee7aa 100644 --- a/quest/m5/net-wrap/e2ee.md +++ b/quest/m5/net-wrap/e2ee.md @@ -21,8 +21,7 @@ the reverse (decided 2026-10-20, maintainer): typed codes (such as an authentication failure) distinguishable rather than collapsing into `Error::Dropped`. - Datagrams: the wrapper's datagram producer and consumer match the - separate datagram types of - [Datagram tracks](/quest/m1/datagram-tracks/README.md), so the trait read + separate datagram track types, so the trait read yields only authenticated datagrams. A datagram that fails authentication, or a duplicate, is dropped there and the track continues. The draft's `authentication` event stays on moq-crypto's own consumer, outside the trait, for callers diff --git a/quest/m5/net-wrap/traits.md b/quest/m5/net-wrap/traits.md index 0b1258599f2..701fae0d39c 100644 --- a/quest/m5/net-wrap/traits.md +++ b/quest/m5/net-wrap/traits.md @@ -37,8 +37,8 @@ the methods exactly as moq-net has them today. wrapper's own subscriber, so E2EE decrypts behind it; `Resolving` and `Fetching` resolve to the wrapper's logical metadata and groups. - Adapters: a subscriber's `ordered` returns its own `track::Ordered` - with the same group and control surface; datagrams leave stream tracks - with [Datagram tracks](/quest/m1/datagram-tracks/README.md). moq-json's snapshot + with the same group and control surface; datagrams live on their own + datagram tracks, apart from stream tracks. moq-json's snapshot and window consumers, moq-mux, and moq-stats read through `ordered()`, so without it they stay concrete. - Listing (maintainer, 2026-10-24): a broadcast consumer's `tracks` diff --git a/rs/moq-relay/src/web.rs b/rs/moq-relay/src/web.rs index 37a8d1a210e..0c5c19aeb5c 100644 --- a/rs/moq-relay/src/web.rs +++ b/rs/moq-relay/src/web.rs @@ -2881,6 +2881,7 @@ mod tests { .await; let (transport, driver) = qmux::ws::Upgraded::new(socket, "qmux-01.moq-lite-06") .connect() + .await .unwrap(); tokio::spawn(driver); let origin = moq_tokio::origin::spawn(); diff --git a/rs/moq-relay/src/websocket.rs b/rs/moq-relay/src/websocket.rs index bb994cc0688..21676e2c23a 100644 --- a/rs/moq-relay/src/websocket.rs +++ b/rs/moq-relay/src/websocket.rs @@ -491,6 +491,7 @@ mod tests { let socket = WebSocketStream::from_raw_socket(TokioIo::new(upgraded), Role::Server, None).await; let (session, driver) = qmux::ws::Upgraded::new(socket, &wire) .accept() + .await .expect("the upgrade selected a QMux subprotocol"); tokio::spawn(driver); let _ = tx.send(Observed { @@ -719,6 +720,7 @@ mod tests { &alpn, ) .connect() + .await .unwrap(); tokio::spawn(driver); @@ -770,6 +772,7 @@ mod tests { &alpn, ) .connect() + .await .unwrap(); tokio::spawn(driver); diff --git a/rs/moq-tokio/src/server.rs b/rs/moq-tokio/src/server.rs index dd105872cab..c4b0318cf77 100644 --- a/rs/moq-tokio/src/server.rs +++ b/rs/moq-tokio/src/server.rs @@ -2202,10 +2202,11 @@ mod tests { let (client, server) = tokio::io::duplex(64 * 1024); let client = WebSocketStream::from_raw_socket(client, Role::Client, None).await; let server = WebSocketStream::from_raw_socket(server, Role::Server, None).await; - ( - crate::spawn_qmux(qmux::ws::Upgraded::new(client, ALPN).connect().unwrap()), - crate::spawn_qmux(qmux::ws::Upgraded::new(server, ALPN).accept().unwrap()), - ) + let (client, server) = tokio::join!( + qmux::ws::Upgraded::new(client, ALPN).connect(), + qmux::ws::Upgraded::new(server, ALPN).accept(), + ); + (crate::spawn_qmux(client.unwrap()), crate::spawn_qmux(server.unwrap())) } /// HTTP connection facts and the admission guard survive the upgraded-socket handoff. @@ -2232,6 +2233,7 @@ mod tests { let client = crate::spawn_qmux( qmux::ws::Upgraded::new(client, "qmux-01.moq-lite-06") .connect() + .await .unwrap(), ); let mut setup = client.open_uni(SendOptions::default()).await.unwrap(); @@ -2271,7 +2273,7 @@ mod tests { ); options.link.alpn = Some(protocol.into()); let accept = tokio::spawn(crate::websocket::accept(server, options)); - let client = crate::spawn_qmux(qmux::ws::Upgraded::new(client, protocol).connect().unwrap()); + let client = crate::spawn_qmux(qmux::ws::Upgraded::new(client, protocol).connect().await.unwrap()); // A single Path parameter, including the empty value: lite uses a // counted parameter bag; IETF uses a u16-sized SETUP option block. let mut bytes = if protocol.contains("moq-lite") { diff --git a/rs/moq-tokio/src/websocket.rs b/rs/moq-tokio/src/websocket.rs index 7991a9d2cf6..2dd7fef9d3f 100644 --- a/rs/moq-tokio/src/websocket.rs +++ b/rs/moq-tokio/src/websocket.rs @@ -181,7 +181,9 @@ where if let Some(stats) = &options.socket_stats { upgraded = upgraded.with_socket_stats(stats.clone()); } - let session = crate::spawn_qmux(upgraded.accept().map_err(Error::accept)?); + // The deadline covers QMux establishment too, which waits for the peer's parameters. + let accepted = async { upgraded.accept().await.map_err(Error::accept) }; + let session = crate::spawn_qmux(crate::server::within(deadline, accepted).await?); crate::server::accept_websocket(session, options, deadline).await }) .await @@ -527,6 +529,7 @@ async fn connect_tls_override( .with_keep_alive(qmux::ws::KeepAlive::default()) .with_session_config(session.clone()) .connect() + .await .map(crate::spawn_qmux) .map_err(Error::connect) } @@ -752,6 +755,7 @@ impl Listener { .with_keep_alive(qmux::ws::KeepAlive::default()) .with_session_config(session) .accept() + .await .map(crate::spawn_qmux) .map_err(Error::accept)?; Ok((session, url, Accepted { remote: addr, protocol })) @@ -951,6 +955,8 @@ mod tests { let server_name = tls.get_ref().1.server_name().map(str::to_string); let host = Arc::new(Mutex::new(None)); let request_host = host.clone(); + let protocol = Arc::new(Mutex::new(None)); + let selected = protocol.clone(); #[expect( clippy::result_large_err, reason = "the error type is tungstenite's handshake response, not ours" @@ -973,12 +979,17 @@ mod tests { http::header::SEC_WEBSOCKET_PROTOCOL, http::HeaderValue::from_str(protocol).unwrap(), ); + *selected.lock().unwrap() = Some(protocol.to_string()); } Ok(response) }; - let _websocket = tokio_tungstenite::accept_hdr_async(tls, callback).await.unwrap(); + let websocket = tokio_tungstenite::accept_hdr_async(tls, callback).await.unwrap(); + let protocol = protocol.lock().unwrap().take().unwrap(); + // The client returns once QMux is established, so answer with its parameters. + let (session, driver) = qmux::ws::Upgraded::new(websocket, &protocol).accept().await.unwrap(); + tokio::spawn(driver); let host = host.lock().unwrap().take(); - (server_name, host) + (server_name, host, session) }); let config = Config::default(); @@ -1002,7 +1013,7 @@ mod tests { .await .unwrap(); drop(session); - let (server_name, host) = accepted.await.unwrap(); + let (server_name, host, _session) = accepted.await.unwrap(); assert_eq!(server_name.as_deref(), expected_sni); assert_eq!(host.as_deref(), Some(expected_host.as_str())); } @@ -1035,7 +1046,7 @@ mod tests { options.quic = quic.resolve(); let server = tokio::spawn(accept(server_ws, options)); - let (session, driver) = qmux::ws::Upgraded::new(client_ws, &alpn).connect().unwrap(); + let (session, driver) = qmux::ws::Upgraded::new(client_ws, &alpn).connect().await.unwrap(); tokio::spawn(driver); // Runs until aborted: its driver sends SETUP, and ending it would cancel the request. let client = tokio::spawn(async move { @@ -1144,6 +1155,33 @@ mod timeout_tests { use futures::FutureExt; use moq_net::transport::poll::Session as _; + /// A peer that upgrades but never sends its QMux parameters is refused at the accept's own + /// deadline, not QMux's longer handshake timeout. + #[tokio::test(start_paused = true)] + async fn silent_qmux_peer_is_refused_at_the_deadline() { + const ALPN: &str = "qmux-01.moq-lite-06"; + let activity = moq_net::server::Activity::default(); + let timeout = time::Duration::from_secs(1); + let mut options = Options::new( + "ws://localhost/".parse().unwrap(), + moq_net::Server::new().with_timeout(Some(timeout)), + activity.enter().unwrap(), + ); + options.link.alpn = Some(ALPN.into()); + let (server, _peer) = tokio::io::duplex(4096); + let server = + tokio_tungstenite::WebSocketStream::from_raw_socket(server, tungstenite::protocol::Role::Server, None) + .await; + let start = kio::clock::now(); + let result = accept(server, options).await; + assert!( + matches!(result, Err(crate::Error::MoqNet(moq_net::Error::Timeout))), + "accept outcome: {:?}", + result.map(|_| ()) + ); + assert_eq!(start.elapsed(), timeout); + } + #[tokio::test(start_paused = true)] async fn the_servers_timeout_bounds_setup() { const ALPN: &str = "qmux-01.moq-lite-06"; @@ -1165,9 +1203,12 @@ mod timeout_tests { let peer = tokio_tungstenite::WebSocketStream::from_raw_socket(peer, tungstenite::protocol::Role::Client, None) .await; - let peer = crate::spawn_qmux(qmux::ws::Upgraded::new(peer, ALPN).connect().unwrap()); let mut accept = Box::pin(accept(server, options)); - assert!(accept.as_mut().now_or_never().is_none()); + // Each end waits for the other's QMux parameters, so the accept runs meanwhile. + let peer = tokio::select! { + peer = qmux::ws::Upgraded::new(peer, ALPN).connect() => crate::spawn_qmux(peer.unwrap()), + result = accept.as_mut() => panic!("accepted before SETUP: {:?}", result.map(|_| ())), + }; let _stream = moq_net::kio::wait(|waiter| peer.poll_open_bi(waiter, Default::default())) .await .unwrap(); diff --git a/rs/moq-tokio/tests/integration/datagram_tracks.rs b/rs/moq-tokio/tests/integration/datagram_tracks.rs new file mode 100644 index 00000000000..5d23061814c --- /dev/null +++ b/rs/moq-tokio/tests/integration/datagram_tracks.rs @@ -0,0 +1,253 @@ +//! Datagram tracks between Rust and JavaScript on lite-07, direct and through a Rust relay. +//! +//! QMux on WebSocket carries the datagrams in order, so every one written after the +//! subscriber's answer must arrive. Broadcast `dg` holds a timed and an untimed datagram +//! track, and a stream track sharing the timed one's name, which must stay independent of +//! it. The JavaScript end is `test/datagram-tracks/client.ts`, which holds the same +//! expectations; it needs Bun, so the interop workflow runs this. +use std::{process::Stdio, time::Duration}; + +use bytes::Bytes; +use moq_net::{Timescale, Timestamp, datagram}; +use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader}; + +const TIMEOUT: Duration = Duration::from_secs(15); +const VERSION: &str = "moq-lite-07-wip"; + +/// The subscriber's priority on `audio`, which the publisher waits to see before writing. +const PRIORITY: i8 = 17; +/// `audio`'s sequence, timestamp in microseconds, and payload. Past 2^53, so a lossy number +/// conversion anywhere on the path shows. +const AUDIO: [(u64, u64, &[u8]); 2] = [(1, 1_234_567, &[1, 2, 3]), ((1 << 53) + 1, 2_000_000, &[4, 5])]; +/// `events`' sequence and payload, untimed. +const EVENTS: [(u64, &[u8]); 2] = [(0, b"hello"), (7, b"")]; +/// The stream track's one frame: its timestamp in milliseconds and payload. +const FRAME: (u64, &[u8]) = (5, &[9]); + +/// One ordered line from a JavaScript peer's stdout. +async fn expect_line(lines: &mut tokio::io::Lines>, want: &str) { + let line = lines + .next_line() + .await + .expect("read the JS peer") + .expect("JS peer exited"); + assert_eq!(line, want, "JS peer line"); +} + +async fn run(relay: bool, js_publishes: bool) { + let version: moq_net::Version = VERSION.parse().unwrap(); + let ws = moq_tokio::websocket::Listener::bind("127.0.0.1:0".parse().unwrap()) + .await + .unwrap() + .with_protocols([version.alpn()]) + .unwrap(); + let url: url::Url = format!("ws://{}", ws.local_addr().unwrap()).parse().unwrap(); + let mut config = moq_tokio::server::Config::default(); + config.listen.version = vec![version]; + config.websocket = Some(ws); + let mut server = config.init_streams().unwrap().listen().await.unwrap(); + + // The Rust end's origin: the server's own session when direct, or a client of the relay. + let local = moq_tokio::origin::spawn(); + let serve = { + let local = local.clone(); + tokio::spawn(async move { + let relayed = moq_tokio::origin::spawn(); + let mut sessions = Vec::new(); + for _ in 0..if relay { 2 } else { 1 } { + let request = server.accept().await.unwrap(); + let request = match (relay, js_publishes) { + (true, _) => request.with_publisher(&relayed).with_subscriber(relayed.clone()), + (false, true) => request.with_subscriber(local.clone()), + (false, false) => request.with_publisher(&local), + }; + sessions.push(request.ok().await.unwrap()); + } + for session in sessions { + let _ = session.closed().await; + } + }) + }; + let mut client = moq_tokio::connect::Config::default(); + client.version = vec![version]; + let client = client.init(Default::default()).unwrap(); + + let spawn = |mode: &str| { + let script = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../../test/datagram-tracks/client.ts"); + let mut child = tokio::process::Command::new("bun") + .arg(script) + .arg(url.as_str()) + .arg(VERSION) + .arg(mode) + .stdin(Stdio::piped()) + .stdout(Stdio::piped()) + .stderr(Stdio::inherit()) + .kill_on_drop(true) + .spawn() + .expect("spawn bun"); + let lines = BufReader::new(child.stdout.take().unwrap()).lines(); + (child, lines) + }; + + let mut sessions = Vec::new(); + if js_publishes { + let (mut child, mut lines) = spawn("publish"); + expect_line(&mut lines, "ready").await; + if relay { + sessions.push( + client + .with_subscriber(local.clone()) + .with_reconnect(false) + .connect(url.clone()) + .established() + .await + .unwrap(), + ); + } + let consumer = local.consume(); + let mut announced = consumer.announced(); + // The `Live` marker can come first while the relay is still learning the route. + while !matches!( + announced.next().await.expect("announcements closed"), + moq_net::announce::Event::Present(_) + ) {} + let broadcast = consumer.request("dg", None).await.unwrap(); + let mut audio = broadcast.datagrams("audio").unwrap(); + audio.set_priority(PRIORITY); + let mut events = broadcast.datagrams("events").unwrap(); + let mut track = broadcast.track("audio").unwrap().subscribe(None).await.unwrap(); + let info = audio.info().await.unwrap(); + assert_eq!(info.timescale, Some(Timescale::MICRO), "audio timescale"); + assert_eq!(info.priority, -7, "audio publisher priority"); + let info = events.info().await.unwrap(); + assert_eq!(info.timescale, None, "events are untimed"); + assert_eq!(info.priority, 0, "events publisher priority"); + assert_eq!(track.info().timescale, Some(Timescale::MILLI), "stream track timescale"); + + let stdin = child.stdin.as_mut().unwrap(); + stdin.write_all(b"send\n").await.unwrap(); + // Datagrams are unordered, so each track's arrive in any order. + let mut got = Vec::new(); + for _ in AUDIO { + got.push(audio.recv().await.unwrap().expect("audio ended early")); + } + got.sort_by_key(|datagram| datagram.sequence); + for ((sequence, micros, payload), got) in AUDIO.into_iter().zip(got) { + assert_eq!(got.sequence, sequence, "audio sequence"); + assert_eq!( + got.timestamp.map(|t| t.as_micros()), + Some(micros.into()), + "audio timestamp" + ); + assert_eq!(got.payload, payload, "audio payload"); + } + let mut got = Vec::new(); + for _ in EVENTS { + got.push(events.recv().await.unwrap().expect("events ended early")); + } + got.sort_by_key(|datagram| datagram.sequence); + for ((sequence, payload), got) in EVENTS.into_iter().zip(got) { + assert_eq!(got.sequence, sequence, "events sequence"); + assert_eq!(got.timestamp, None, "an untimed datagram has no timestamp"); + assert_eq!(got.payload, payload, "events payload"); + } + let mut group = track.recv_group().await.unwrap().expect("stream track ended early"); + let frame = group.read_frame().await.unwrap().expect("group ended early"); + assert_eq!( + frame.timestamp.map(|t| t.as_millis()), + Some(FRAME.0.into()), + "frame timestamp" + ); + assert_eq!(frame.payload, FRAME.1, "frame payload"); + + stdin.write_all(b"finish\n").await.unwrap(); + assert_eq!(audio.recv().await.unwrap(), None, "audio ends"); + assert_eq!(events.recv().await.unwrap(), None, "events end"); + assert!(track.recv_group().await.unwrap().is_none(), "stream track ends"); + drop(child.stdin.take()); + assert!(child.wait().await.unwrap().success(), "JS publisher failed"); + } else { + let route = local.route("dg", moq_net::origin::RouteOptions::hidden()).unwrap(); + let mut audio = route + .broadcast() + .create_datagrams( + "audio", + datagram::Info::default() + .with_timescale(Timescale::MICRO) + .with_priority(-7), + ) + .unwrap(); + let mut events = route + .broadcast() + .create_datagrams("events", datagram::Info::default()) + .unwrap(); + let mut track = route + .broadcast() + .create_track( + "audio", + moq_net::track::Info::default().with_timescale(Timescale::MILLI), + ) + .unwrap(); + route.announce().unwrap(); + if relay { + sessions.push( + client + .with_publisher(&local) + .with_reconnect(false) + .connect(url.clone()) + .established() + .await + .unwrap(), + ); + } + + let (mut child, mut lines) = spawn("subscribe"); + expect_line(&mut lines, "subscribed").await; + let mut priority = None; + while priority != Some(PRIORITY) { + priority = kio::wait(|waiter| audio.poll_priority(waiter, priority)).await; + } + for (sequence, micros, payload) in AUDIO { + audio + .insert(datagram::Datagram { + sequence, + timestamp: Some(Timestamp::from_micros(micros).unwrap()), + payload: Bytes::from_static(payload), + }) + .unwrap(); + } + for (sequence, payload) in EVENTS { + events + .insert(datagram::Datagram { + sequence, + timestamp: None, + payload: Bytes::from_static(payload), + }) + .unwrap(); + } + track + .write_frame(Timestamp::from_millis(FRAME.0).unwrap(), FRAME.1) + .unwrap(); + + expect_line(&mut lines, "received").await; + audio.finish(); + events.finish(); + track.finish().unwrap(); + drop(child.stdin.take()); + assert!(child.wait().await.unwrap().success(), "JS subscriber failed"); + } + drop(sessions); + serve.await.unwrap(); +} + +#[tokio::test] +#[ignore = "requires Bun; run by just test datagram-tracks in the interop workflow"] +async fn datagram_tracks_javascript() { + for relay in [false, true] { + for js_publishes in [false, true] { + kio::clock::timeout(TIMEOUT, run(relay, js_publishes)) + .await + .unwrap_or_else(|_| panic!("timed out: relay {relay}, JS publishes {js_publishes}")); + } + } +} diff --git a/rs/moq-tokio/tests/integration/main.rs b/rs/moq-tokio/tests/integration/main.rs index ad9fb70c62d..7b8245dc69b 100644 --- a/rs/moq-tokio/tests/integration/main.rs +++ b/rs/moq-tokio/tests/integration/main.rs @@ -7,6 +7,7 @@ mod backend; mod broadcast; mod close_code; mod datagram_delivery; +mod datagram_tracks; mod fresh_port; mod keylog; mod max_age; diff --git a/rs/qmux/benches/receive.rs b/rs/qmux/benches/receive.rs index a412ed1cc0a..29d0adb5c6b 100644 --- a/rs/qmux/benches/receive.rs +++ b/rs/qmux/benches/receive.rs @@ -97,15 +97,17 @@ impl Receivers { use qmux::ws::{Upgraded, tokio_tungstenite::WebSocketStream, tungstenite::protocol::Role}; let client = WebSocketStream::from_raw_socket(client, Role::Client, None).await; let server = WebSocketStream::from_raw_socket(server, Role::Server, None).await; - let (client, driver) = Upgraded::new(client, version.alpn()) - .with_session_config(config.clone()) - .connect() - .unwrap(); + let (client, server) = tokio::join!( + Upgraded::new(client, version.alpn()) + .with_session_config(config.clone()) + .connect(), + Upgraded::new(server, version.alpn()) + .with_session_config(config.clone()) + .accept(), + ); + let (client, driver) = client.unwrap(); rig.drivers.spawn(driver); - let (server, driver) = Upgraded::new(server, version.alpn()) - .with_session_config(config.clone()) - .accept() - .unwrap(); + let (server, driver) = server.unwrap(); rig.drivers.spawn(driver); (client, server) } else { diff --git a/rs/qmux/src/session.rs b/rs/qmux/src/session.rs index 543e6f08566..49d5e5782e3 100644 --- a/rs/qmux/src/session.rs +++ b/rs/qmux/src/session.rs @@ -152,21 +152,27 @@ impl Session { /// if the peer completes the transport handshake but never sends its parameters, this /// returns [`Error::HandshakeTimeout`] rather than hanging. pub async fn connect(transport: T, config: Config) -> Result<(Session, Driver), Error> { - let (session, mut driver) = Self::new(transport, Side::Client, config)?; - let session = session.established(&mut driver).await?; - Ok((session, driver)) + Self::start(transport, Side::Client, config).await } /// Open a server-side session over the given transport, waiting until it is /// established. See [`Session::connect`] for the semantics. pub async fn accept(transport: T, config: Config) -> Result<(Session, Driver), Error> { - let (session, mut driver) = Self::new(transport, Side::Server, config)?; + Self::start(transport, Side::Server, config).await + } + + /// Start a session over the transport and wait until it is established. + pub(crate) async fn start( + transport: T, + side: Side, + config: Config, + ) -> Result<(Session, Driver), Error> { + let (session, mut driver) = Self::new(transport, side, config)?; let session = session.established(&mut driver).await?; Ok((session, driver)) } - /// Start a session over the transport without waiting for the handshake, for callers - /// that resolved the protocol out of band (the WebSocket subprotocol, say). + /// Start a session over the transport without waiting for the handshake. pub(crate) fn new(mut transport: T, side: Side, config: Config) -> Result<(Self, Driver), Error> { let conn = mux::Connection::new(config.to_mux()?, side, kio::clock::now()); transport.bind(&config); diff --git a/rs/qmux/src/ws.rs b/rs/qmux/src/ws.rs index 427fe6feb04..6c243ee510b 100644 --- a/rs/qmux/src/ws.rs +++ b/rs/qmux/src/ws.rs @@ -125,10 +125,8 @@ where /// Use `config` for every session setting except the wire-format version /// and application protocol, which the handshake negotiates. /// - /// The WebSocket handshake already settled the protocol, so the session starts - /// without awaiting the peer's transport parameters, failing later with - /// [`Error::HandshakeTimeout`] if they never arrive. Cap the socket's message and - /// frame sizes at [`max_message_size`] of `config`, since each record is one message. + /// Cap the socket's message and frame sizes at [`max_message_size`] of `config`, + /// since each record is one message. pub fn with_session_config(mut self, config: Config) -> Self { self.session = config; self @@ -146,28 +144,28 @@ where self } - /// Wrap as a client-side session, returned with the [`Driver`] to spawn. + /// Wrap as a client-side session once it is established, returned with the + /// [`Driver`] to spawn. /// - /// The protocol is already known from the negotiated subprotocol (ALPN), so - /// this returns synchronously without awaiting in-band parameters. Fails when - /// the subprotocol names no QMux version. - pub fn connect(self) -> Result<(Session, Driver>), Error> { - self.start(Side::Client) + /// As with [`Session::connect`], established means the peer's transport parameters + /// arrived, so its stream and datagram limits are known. Fails when the subprotocol + /// names no QMux version, or with [`Error::HandshakeTimeout`] if the parameters never + /// arrive. + pub async fn connect(self) -> Result<(Session, Driver>), Error> { + self.start(Side::Client).await } - /// Wrap as a server-side session, returned with the [`Driver`] to spawn. - /// - /// As with [`connect`](Self::connect), the protocol is known from the - /// negotiated subprotocol, so this returns synchronously. - pub fn accept(self) -> Result<(Session, Driver>), Error> { - self.start(Side::Server) + /// Wrap as a server-side session once it is established, as with + /// [`connect`](Self::connect). + pub async fn accept(self) -> Result<(Session, Driver>), Error> { + self.start(Side::Server).await } - fn start(self, side: Side) -> Result<(Session, Driver>), Error> { + async fn start(self, side: Side) -> Result<(Session, Driver>), Error> { let (version, protocol) = alpn::parse(Some(&self.alpn))?; let config = self.session.clone().with_negotiated(version, protocol); let transport = self.into_transport()?; - Session::new(transport, side, config) + Session::start(transport, side, config).await } fn into_transport(self) -> Result, Error> { @@ -267,7 +265,8 @@ impl Client { self } - /// Connect to a WebSocket server, negotiating an advertised `(alpn, version)`. + /// Connect to a WebSocket server, negotiating an advertised `(alpn, version)`, and + /// return the session once it is established. pub async fn connect( &self, url: &str, @@ -357,8 +356,7 @@ impl Client { Some(ka) => transport.with_keep_alive(ka)?, None => transport, }; - // Protocol came from the negotiated subprotocol, so no in-band wait. - Session::new(transport, Side::Client, config) + Session::start(transport, Side::Client, config).await } } @@ -432,7 +430,8 @@ impl Server { self } - /// Accept a WebSocket connection, negotiating an offered `(alpn, version)`. + /// Accept a WebSocket connection, negotiating an offered `(alpn, version)`, and + /// return the session once it is established. /// /// Disable Nagle on a TCP `socket` first (`set_nodelay(true)`): records are /// already batched, so Nagle would only hold a batch's tail for the peer's ACK. @@ -526,15 +525,13 @@ impl Server { Some(ka) => transport.with_keep_alive(ka)?, None => transport, }; - // Protocol came from the negotiated subprotocol, so no in-band wait. - Session::new(transport, Side::Server, config) + Session::start(transport, Side::Server, config).await } } #[cfg(test)] mod tests { use super::*; - use moq_net::transport::poll::Session as _; use tokio::io::AsyncWriteExt; /// A frame declaring more than one record is refused at its header rather than @@ -551,17 +548,21 @@ mod tests { ) .await .unwrap(); - let (session, driver) = accept.await.unwrap().unwrap(); - tokio::spawn(driver); - - // A masked binary frame declaring 1 MiB, with none of its payload sent. + // A masked binary frame declaring 1 MiB, with none of its payload sent, before the + // client's transport parameters: the accept fails on it rather than awaiting them. let mut frame = vec![0x82, 0x80 | 127]; frame.extend_from_slice(&(1u64 << 20).to_be_bytes()); frame.extend_from_slice(&[0; 4]); client.write_all(&frame).await.unwrap(); - kio::clock::timeout(Duration::from_secs(1), session.closed()) + let accepted = kio::clock::timeout(Duration::from_secs(1), accept) .await - .expect("the socket waited to buffer a frame larger than a record"); + .expect("the socket waited to buffer a frame larger than a record") + .unwrap(); + assert!( + matches!(&accepted, Err(err) if !matches!(err, Error::HandshakeTimeout)), + "{:?}", + accepted.map(|_| ()) + ); } } diff --git a/test/datagram-tracks/client.ts b/test/datagram-tracks/client.ts new file mode 100644 index 00000000000..6ef4da50a2f --- /dev/null +++ b/test/datagram-tracks/client.ts @@ -0,0 +1,169 @@ +/** + * The JavaScript peer of `just test datagram-tracks`: publishes or reads broadcast `dg` over + * QMux on WebSocket, which carries datagrams in order, so a delivery the test misses is a bug. + * + * `dg` holds a timed datagram track `audio`, an untimed datagram track `events`, and a + * stream track also named `audio`, which a datagram track never shares a namespace with. + * + * bun client.ts URL ALPN publish # prints `ready`, then reads `send` and `finish` lines + * bun client.ts URL ALPN subscribe # prints `subscribed`, then `received` once it read the data + * + * The Rust test (rs/moq-tokio/tests/integration/datagram_tracks.rs) drives either end and + * carries the same expectations. + * + * @module + */ +import assert from "node:assert/strict"; +import Session from "@moq/qmux"; +import * as Moq from "../../js/net/src/index.ts"; + +// stdout carries the handshake to the Rust test, so library debug logs go to stderr. +console.debug = console.error; + +const [address, protocol, mode] = process.argv.slice(2); +if (!address || !protocol || !["publish", "subscribe"].includes(mode)) + throw new Error("expected URL ALPN publish|subscribe"); + +// The subscriber's priority on `audio`, which the publisher waits to see before writing. +const PRIORITY = 17; +// Past 2^53, so a lossy number conversion anywhere on the path shows. +const AUDIO = [ + { sequence: 1n, micros: 1_234_567, payload: [1, 2, 3] }, + { sequence: (1n << 53n) + 1n, micros: 2_000_000, payload: [4, 5] }, +]; +const EVENTS = [ + { sequence: 0n, payload: [...new TextEncoder().encode("hello")] }, + { sequence: 7n, payload: [] }, +]; +const FRAME = { millis: 5, payload: [9] }; + +const origin = new Moq.Origin.Producer(); +const url = new URL(address); +const transport = new Session(url, { protocols: [protocol], versions: { [protocol]: null }, requireProtocol: true }); +await transport.ready; +const session = await Moq.Connection.connect({ + url, + transport, + publish: mode === "publish" ? origin.consume() : undefined, + consume: mode === "subscribe" ? origin : undefined, +}); + +const lines = (async function* () { + let buffered = ""; + for await (const chunk of Bun.stdin.stream().pipeThrough(new TextDecoderStream())) { + buffered += chunk; + for (let end = buffered.indexOf("\n"); end >= 0; end = buffered.indexOf("\n")) { + yield buffered.slice(0, end); + buffered = buffered.slice(end + 1); + } + } +})(); + +/** `count` datagrams from `track`, sorted by sequence. */ +async function recvAll(track: Moq.Datagram.Consumer, count: number): Promise { + const got = []; + while (got.length < count) { + const datagram = await track.recv(); + assert(datagram, `${track.name} ended early`); + got.push(datagram); + } + return got.sort((a, b) => (a.sequence < b.sequence ? -1 : 1)); +} + +async function expectLine(want: string) { + const { value } = await lines.next(); + assert.equal(value, want, `expected ${want} from the test`); +} + +try { + if (mode === "publish") { + const route = origin.route(Moq.Path.from("dg"), { hidden: true }); + const audio = route.broadcast.createDatagrams("audio", { timescale: Moq.Time.Timescale.MICRO, priority: -7 }); + const events = route.broadcast.createDatagrams("events"); + const track = route.broadcast.createTrack("audio", { timescale: Moq.Time.Timescale.MILLI }); + route.announce(); + console.log("ready"); + + await expectLine("send"); + while (audio.priority.peek() !== PRIORITY) await audio.priority.changed(); + for (const { sequence, micros, payload } of AUDIO) + audio.insert({ + sequence, + timestamp: Moq.Time.Timestamp.fromMicros(micros), + payload: new Uint8Array(payload), + }); + for (const { sequence, payload } of EVENTS) events.insert({ sequence, payload: new Uint8Array(payload) }); + track.writeFrame({ + timestamp: Moq.Time.Timestamp.fromMillis(FRAME.millis), + payload: new Uint8Array(FRAME.payload), + }); + + await expectLine("finish"); + audio.finish(); + events.finish(); + track.finish(); + // The test closes stdin once the subscriber has read the end. + assert.equal((await lines.next()).done, true, "unexpected line from the test"); + } else { + const announcements = origin.consume().announced(); + // `live` can come first while a relay has yet to learn the publisher's route. + for (;;) { + const event = await announcements.next(); + assert(event, "announcements closed"); + if (event.kind === "present" && event.prefix === "dg") break; + } + announcements.close(); + const request = origin.consume().request(Moq.Path.from("dg")); + let broadcast = request.active.peek(); + while (!broadcast) broadcast = await request.active.changed(); + + const audio = broadcast.datagrams("audio"); + audio.setPriority(PRIORITY); + const events = broadcast.datagrams("events"); + const track = broadcast.track("audio").subscribe(); + const audioInfo = await audio.info(); + assert.equal(audioInfo.timescale, Moq.Time.Timescale.MICRO, "audio timescale"); + assert.equal(audioInfo.priority, -7, "audio publisher priority"); + const eventsInfo = await events.info(); + assert.equal(eventsInfo.timescale ?? undefined, undefined, "events are untimed"); + assert.equal(eventsInfo.priority, 0, "events publisher priority"); + assert.equal((await track.info()).timescale, Moq.Time.Timescale.MILLI, "stream track timescale"); + // Answered, so what the publisher writes from now on reaches this session. + console.log("subscribed"); + + // Datagrams are unordered, so each track's arrive in any order. + const audioGot = await recvAll(audio, AUDIO.length); + for (const [i, want] of AUDIO.entries()) { + const got = audioGot[i]; + assert.equal(got.sequence, want.sequence, "audio sequence"); + assert.equal(got.timestamp?.asMicros(), want.micros, "audio timestamp"); + assert.deepEqual([...got.payload], want.payload, "audio payload"); + } + const eventsGot = await recvAll(events, EVENTS.length); + for (const [i, want] of EVENTS.entries()) { + const got = eventsGot[i]; + assert.equal(got.sequence, want.sequence, "events sequence"); + assert.equal(got.timestamp, undefined, "an untimed datagram has no timestamp"); + assert.deepEqual([...got.payload], want.payload, "events payload"); + } + const group = await track.recvGroup(); + assert(group, "stream track ended early"); + const frame = await group.readFrame(); + assert(frame, "group ended early"); + assert.equal(frame.timestamp?.asMillis(), FRAME.millis, "frame timestamp"); + assert.deepEqual([...frame.payload], FRAME.payload, "frame payload"); + group.close(); + console.log("received"); + + assert.equal(await audio.recv(), undefined, "audio ends"); + assert.equal(await events.recv(), undefined, "events end"); + assert.equal(await track.recvGroup(), undefined, "stream track ends"); + audio.close(); + events.close(); + track.close(); + request.close(); + } +} finally { + await session.close(); + origin.close(); +} diff --git a/test/justfile b/test/justfile index 060ce9fda5b..cd07d88ea41 100644 --- a/test/justfile +++ b/test/justfile @@ -258,6 +258,10 @@ video: max-age: bash ../sh/local.sh cargo nextest run --locked -p moq-tokio --test integration -E 'test(/^max_age::/)' --run-ignored all +# Datagram tracks between Rust and JavaScript on lite-07, direct and through a Rust relay. +datagram-tracks: + bash ../sh/local.sh cargo nextest run --locked -p moq-tokio --test integration -E 'test(/^datagram_tracks::/)' --run-ignored only + # JavaScript publisher and reader over WebSocket, through a Rust relay, past qmux's default stream limit. stream-limits: bash ../sh/local.sh cargo nextest run --locked -p moq-tokio --test integration -E 'test(/^stream_limits::/)' --run-ignored only