From d776066517ecb496873ef153ece7c0c9bb37a9af Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 29 Oct 2026 09:59:58 -0700 Subject: [PATCH 1/3] chore(quest): claim quest/m1/api-audit/qmux-datagrams.md Quest-Claim: 89145ab3851607f4 From 0e8bdc641e041bbced45d19bc06e6b448d3b9dca Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 29 Oct 2026 10:10:52 -0700 Subject: [PATCH 2/3] fix(qmux)!: enforce datagram policy and hide transport mutators Co-Authored-By: GPT-6.1 Sol --- js/qmux/README.md | 15 +++ js/qmux/api/index.api.md | 16 +-- js/qmux/bench/datagrams.ts | 58 ++++++++++ js/qmux/src/index.ts | 2 +- js/qmux/src/session.test.ts | 162 +++++++++++++++++++++++++++ js/qmux/src/session.ts | 156 ++++++++++++++++++-------- quest/m1/api-audit/qmux-datagrams.md | 57 ++++------ 7 files changed, 367 insertions(+), 99 deletions(-) create mode 100644 js/qmux/bench/datagrams.ts diff --git a/js/qmux/README.md b/js/qmux/README.md index dfc983f5f5a..29a26e8dc0f 100644 --- a/js/qmux/README.md +++ b/js/qmux/README.md @@ -23,6 +23,21 @@ await transport.ready const stream = await transport.createBidirectionalStream() ``` +### Datagrams + +Use `transport.datagrams.readable` to receive packets and `.writable` to send them. +`.maxDatagramSize` reports the negotiated payload limit; oversized or unsupported writes are dropped. +The datagram transport is created and managed by the session. + +Set `.incomingHighWaterMark` to change the live receive queue limit (1024 packets by default). +New arrivals are dropped when the queue reaches that limit. Lowering it preserves queued packets +until they are read. Values below 1 are clamped to 1; negative values and `NaN` throw `RangeError`. +The value must be a number. + +Expiry and changes to the outbound queue policy are unsupported. Assigning anything except `null` +to `.incomingMaxAge` or `.outgoingMaxAge`, or anything except 1024 to `.outgoingHighWaterMark`, +throws `NotSupportedError`. + ### Servers `Session.accept` runs the other role, over a WebSocket your server has already accepted. The host diff --git a/js/qmux/api/index.api.md b/js/qmux/api/index.api.md index abc74ac0f83..25d0e1d16cd 100644 --- a/js/qmux/api/index.api.md +++ b/js/qmux/api/index.api.md @@ -15,20 +15,6 @@ export interface Config { streamReceiveWindow?: bigint; } -export class Datagrams implements WebTransportDatagramDuplexStream { - constructor(send: (data: Uint8Array) => void); - close(err?: Error): void; - incomingHighWaterMark: number; - incomingMaxAge: number | null; - get maxDatagramSize(): number; - outgoingHighWaterMark: number; - outgoingMaxAge: number | null; - push(data: Uint8Array): void; - readonly readable: ReadableStream; - setMaxDatagramSize(size: number): void; - readonly writable: WritableStream; -} - export interface InstallOptions { requireProtocol?: boolean; versions?: Record; @@ -120,7 +106,7 @@ export default class implements WebTransport { get congestionControl(): WebTransportCongestionControl; createBidirectionalStream(options?: SendStreamOptions): Promise; createUnidirectionalStream(options?: SendStreamOptions): Promise>; - readonly datagrams: Datagrams; + get datagrams(): WebTransportDatagramDuplexStream; getStats(): Promise<{ datagrams: {}; }>; diff --git a/js/qmux/bench/datagrams.ts b/js/qmux/bench/datagrams.ts new file mode 100644 index 00000000000..5542e1f70d9 --- /dev/null +++ b/js/qmux/bench/datagrams.ts @@ -0,0 +1,58 @@ +/** Sweep receive-queue draining over backlog size through the public session API. */ +import * as Frame from "../src/frame.ts"; +import Session from "../src/session.ts"; +import type { WebSocketStreamCloseEvent } from "../src/web-socket-stream.ts"; + +const packet = Frame.encode({ type: "datagram", data: new Uint8Array(1200) }, "qmux-01"); + +async function measure(backlog: number): Promise { + let incoming!: ReadableStreamDefaultController; + const pong = Promise.withResolvers(); + const closed = Promise.withResolvers(); + const session = Session.accept( + { + url: "https://example.test/qmux-bench", + opened: Promise.resolve({ + protocol: "qmux-01", + extensions: "", + readable: new ReadableStream({ + start: (controller) => { + incoming = controller; + }, + }), + writable: new WritableStream({ + write: (bytes) => { + if (Frame.decodeRecord(bytes).some((frame) => frame.type === "ping_response")) pong.resolve(); + }, + }), + }), + closed: closed.promise, + close: () => closed.resolve({ closeCode: 1000, reason: "" }), + }, + { config: { idleTimeout: null } }, + ); + await session.ready; + session.datagrams.incomingHighWaterMark = backlog; + for (let index = 0; index < backlog; index++) incoming.enqueue(packet); + incoming.enqueue(Frame.encode({ type: "ping_request", sequence: 0n }, "qmux-01")); + await pong.promise; + const reader = session.datagrams.readable.getReader(); + const start = performance.now(); + for (let index = 0; index < backlog; index++) { + const result = await reader.read(); + if (result.done || result.value.byteLength !== 1200) throw new Error("missing datagram"); + } + const elapsed = ((performance.now() - start) * 1000) / backlog; + await reader.cancel(); + session.close(); + await closed.promise; + return elapsed; +} + +console.log("backlog,median_us_per_read"); +for (const backlog of [1, 32, 1024, 16384]) { + const samples: number[] = []; + for (let run = 0; run < 7; run++) samples.push(await measure(backlog)); + samples.sort((a, b) => a - b); + console.log(`${backlog},${samples[3].toFixed(3)}`); +} diff --git a/js/qmux/src/index.ts b/js/qmux/src/index.ts index 6790ee32bf8..c1c37522f97 100644 --- a/js/qmux/src/index.ts +++ b/js/qmux/src/index.ts @@ -4,7 +4,7 @@ import Session from "./session.ts"; export { SessionError, StreamError } from "./error.ts"; export type { AcceptOptions, Config, SendStreamOptions, SessionOptions, Version } from "./session.ts"; -export { Datagrams, selectSubprotocol } from "./session.ts"; +export { selectSubprotocol } from "./session.ts"; export type { WebSocketLike, WebSocketStreamCloseEvent, diff --git a/js/qmux/src/session.test.ts b/js/qmux/src/session.test.ts index 5135e362c08..74745879822 100644 --- a/js/qmux/src/session.test.ts +++ b/js/qmux/src/session.test.ts @@ -3,6 +3,7 @@ import { type Installed, Manual, Milli, Nano } from "@moq/clock"; import { SessionError, StreamError } from "./error.ts"; import * as Frame from "./frame.ts"; import { DEFAULT_MAX_RECORD_SIZE, type TransportParams } from "./frame.ts"; +import * as QMux from "./index.ts"; import Session, { type Config } from "./session.ts"; import * as Stream from "./stream.ts"; import { VarInt } from "./varint.ts"; @@ -31,6 +32,7 @@ class FakePeer { #writeBlocked: Promise | undefined; #writeError: Error | undefined; #unblockWrites: (() => void) | undefined; + #pongResolve?: () => void; /** Raw chunks the Session has written. */ sent: Uint8Array[] = []; @@ -56,6 +58,10 @@ class FakePeer { await this.#writeBlocked; if (this.#writeError) throw this.#writeError; this.sent.push(chunk); + if (this.#pongResolve && Frame.decodeRecord(chunk).some((frame) => frame.type === "ping_response")) { + this.#pongResolve(); + this.#pongResolve = undefined; + } }, }); this.opened = Promise.resolve({ readable, writable, protocol, extensions: "" }); @@ -94,6 +100,14 @@ class FakePeer { } // --- test controls --- + /** Wait until the session has handled all preceding inbound frames. */ + barrier(): Promise { + const pong = Promise.withResolvers(); + this.#pongResolve = pong.resolve; + this.send({ type: "ping_request", sequence: 0n }); + return pong.promise; + } + /** Inject a frame as if sent by the peer. */ send(frame: Frame.Any) { this.#recv.enqueue(Frame.encode(frame, "qmux-01")); @@ -1412,6 +1426,154 @@ describe("Session integration (scripted peer)", () => { expect(sentClose(peer)?.type).toBe("connection_close"); }); + test("datagrams: lowering the live high-water mark retains backlog and sheds later overflow", async () => { + const { session, peer } = connect(); + await session.ready; + const datagrams = session.datagrams; + datagrams.incomingHighWaterMark = 3; + for (const value of [1, 2]) peer.send({ type: "datagram", data: new Uint8Array([value]) }); + await peer.barrier(); + + datagrams.incomingHighWaterMark = 1; + peer.send({ type: "datagram", data: new Uint8Array([3]) }); + await peer.barrier(); + const reader = datagrams.readable.getReader(); + expect((await reader.read()).value).toEqual(new Uint8Array([1])); + peer.send({ type: "datagram", data: new Uint8Array([4]) }); + await peer.barrier(); + expect((await reader.read()).value).toEqual(new Uint8Array([2])); + peer.send({ type: "datagram", data: new Uint8Array([5]) }); + await peer.barrier(); + session.close(); + expect((await reader.read()).value).toEqual(new Uint8Array([5])); + expect((await reader.read()).done).toBe(true); + }); + + test("datagrams: raising the live high-water mark admits more queued packets", async () => { + const { session, peer } = connect(); + await session.ready; + session.datagrams.incomingHighWaterMark = 1; + for (const value of [1, 2]) peer.send({ type: "datagram", data: new Uint8Array([value]) }); + await peer.barrier(); + session.datagrams.incomingHighWaterMark = 3; + for (const value of [3, 4, 5]) peer.send({ type: "datagram", data: new Uint8Array([value]) }); + await peer.barrier(); + session.close(); + const received: number[] = []; + for await (const data of session.datagrams.readable) received.push(data[0]); + expect(received).toEqual([1, 3, 4]); + }); + + test("datagrams: the live limit validates input without changing the previous policy", async () => { + const { session } = connect(); + await session.ready; + const datagrams = session.datagrams; + for (const value of [0, -0, 0.5, 1.5, Infinity]) { + datagrams.incomingHighWaterMark = value; + expect(datagrams.incomingHighWaterMark).toBe(Math.max(1, value)); + } + datagrams.incomingHighWaterMark = 2; + for (const value of [NaN, -1, -Infinity]) { + expect(() => { + datagrams.incomingHighWaterMark = value; + }).toThrow(RangeError); + expect(datagrams.incomingHighWaterMark).toBe(2); + } + for (const value of [undefined, null, "2", {}, 2n]) { + expect(() => { + Reflect.set(datagrams, "incomingHighWaterMark", value); + }).toThrow(TypeError); + expect(datagrams.incomingHighWaterMark).toBe(2); + } + session.close(); + }); + + test("datagrams: unsupported policies accept only their defaults", async () => { + const { session } = connect(); + await session.ready; + const datagrams = session.datagrams; + for (const [field, defaultValue] of [ + ["incomingMaxAge", null], + ["outgoingMaxAge", null], + ["outgoingHighWaterMark", 1024], + ] as const) { + expect(Reflect.set(datagrams, field, defaultValue)).toBe(true); + for (const value of [0, 1, -1, NaN, Infinity, undefined, "1024"]) { + try { + Reflect.set(datagrams, field, value); + throw new Error("unsupported datagram policy was accepted"); + } catch (err) { + expect(err).toBeInstanceOf(DOMException); + expect((err as DOMException).name).toBe("NotSupportedError"); + } + expect(datagrams[field]).toBe(defaultValue); + } + } + session.close(); + }); + + test("datagrams: pending reads bypass the queue and draining frees capacity", async () => { + const { session, peer } = connect(); + await session.ready; + session.datagrams.incomingHighWaterMark = 1; + const reader = session.datagrams.readable.getReader(); + const pending = reader.read(); + for (const value of [1, 2, 3]) peer.send({ type: "datagram", data: new Uint8Array([value]) }); + await peer.barrier(); + expect((await pending).value).toEqual(new Uint8Array([1])); + expect((await reader.read()).value).toEqual(new Uint8Array([2])); + peer.send({ type: "datagram", data: new Uint8Array([4]) }); + await peer.barrier(); + expect((await reader.read()).value).toEqual(new Uint8Array([4])); + session.close(); + expect((await reader.read()).done).toBe(true); + }); + + 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; + session.datagrams.incomingHighWaterMark = 1; + if (queued) { + peer.send({ type: "datagram", data: new Uint8Array([1]) }); + await peer.barrier(); + } + const reader = session.datagrams.readable.getReader(); + const pending = queued ? undefined : reader.read(); + await reader.cancel(); + if (pending) expect((await pending).done).toBe(true); + session.datagrams.incomingHighWaterMark = 2; + peer.send({ type: "datagram", data: new Uint8Array([2]) }); + await peer.barrier(); + expect((await reader.read()).done).toBe(true); + session.close(); + await session.closed; + }); + } + + test("datagrams: session failure discards queued packets and rejects reads", async () => { + const { session, peer } = connect(); + await session.ready; + session.datagrams.incomingHighWaterMark = 1; + peer.send({ type: "datagram", data: new Uint8Array([1]) }); + await peer.barrier(); + peer.error(); + await expectSessionFailure(session); + await expect(session.datagrams.readable.getReader().read()).rejects.toThrow("socket error"); + }); + + test("datagrams: the runtime view has no constructor or transport mutators for applications", async () => { + const { session } = connect(); + await session.ready; + const datagrams = session.datagrams; + expect("Datagrams" in QMux).toBe(false); + for (const key of ["push", "close", "setMaxDatagramSize"]) expect(key in datagrams).toBe(false); + expect(() => Reflect.construct(datagrams.constructor, [() => {}])).toThrow(TypeError); + expect(Reflect.set(datagrams, "maxDatagramSize", 100)).toBe(false); + expect(Reflect.set(session, "datagrams", {})).toBe(false); + session.close(); + }); + test("datagrams: an app write produces a DATAGRAM frame on the wire", async () => { const { session, peer } = connect(); await session.ready; diff --git a/js/qmux/src/session.ts b/js/qmux/src/session.ts index e1f3725247d..a5f9576dfc2 100644 --- a/js/qmux/src/session.ts +++ b/js/qmux/src/session.ts @@ -41,7 +41,7 @@ export interface Config { maxRecordSize?: bigint; /** Largest DATAGRAM *frame* (RFC 9221: type + length + payload) we advertise * willingness to receive; null disables datagrams. This is a frame size, not a - * payload size — {@link Datagrams.maxDatagramSize} reports the usable payload + * payload size; `Session.datagrams.maxDatagramSize` reports the usable payload * (this value less framing overhead). Keep it at or below `maxRecordSize`. * Datagrams are a record-framed-draft feature (qmux-01+); this is ignored on * qmux-00. Defaults to a full record. */ @@ -111,86 +111,142 @@ function configToTransportParams(config: Required): TransportParams { }; } -/** `WebTransportDatagramDuplexStream` (RFC 9221) backed by QMux DATAGRAM frames. - * - * Datagrams are unreliable: the inbound `readable` is a fixed-capacity queue that - * drops when a slow reader lets it fill, and an outbound payload larger than - * {@link maxDatagramSize} (or one sent before the peer advertised support) is - * silently discarded, matching the W3C WebTransport semantics. - */ -export class Datagrams implements WebTransportDatagramDuplexStream { - /** Inbound datagrams the readable queues before dropping more; fixed at construction. */ - incomingHighWaterMark = 1024; - /** Part of the WebTransport interface; unused, since a datagram never expires here. */ - incomingMaxAge: number | null = null; - /** Part of the WebTransport interface; unused, since a datagram is sent once written. */ - outgoingHighWaterMark = 1024; - /** Part of the WebTransport interface; unused, since a datagram never expires here. */ - outgoingMaxAge: number | null = null; +// Only the session can construct or mutate the datagram transport. +const datagramsKey = Symbol("Datagrams"); +let makeDatagrams: (send: (data: Uint8Array) => void) => Datagrams; +let pushDatagram: (datagrams: Datagrams, data: Uint8Array) => void; +let setMaxDatagramSize: (datagrams: Datagrams, size: number) => void; +let closeDatagrams: (datagrams: Datagrams, err?: Error) => void; +/** WebTransport datagrams with a live inbound queue limit and no expiry. */ +class Datagrams implements WebTransportDatagramDuplexStream { /** The datagrams the peer sends. */ readonly readable: ReadableStream; /** The datagrams to send to the peer. */ readonly writable: WritableStream; + #incomingHighWaterMark = 1024; #incoming!: ReadableStreamDefaultController; + #pending: Uint8Array[] = []; + #pullResolve?: () => void; + #closed = false; // Resolved from the peer's transport parameters once the handshake completes; // 0 until then (and forever if the peer doesn't accept datagrams). #maxDatagramSize = 0; - #send: (data: Uint8Array) => void; - /** @param send - Enqueue a datagram payload onto the wire (best-effort). */ - constructor(send: (data: Uint8Array) => void) { - this.#send = send; - // A bounded queue: `pull` is a no-op, so `desiredSize` reflects the - // backlog and #push drops once it's full rather than buffering unboundedly. + private constructor(key: typeof datagramsKey, send: (data: Uint8Array) => void) { + if (key !== datagramsKey) throw new TypeError("Datagrams can only be constructed by Session"); this.readable = new ReadableStream( { start: (controller) => { this.#incoming = controller; }, + pull: () => { + const data = this.#pending.shift(); + if (data) this.#incoming.enqueue(data); + if (this.#closed && this.#pending.length === 0) this.#incoming.close(); + if (data || this.#closed) return; + return new Promise((resolve) => { + this.#pullResolve = resolve; + }); + }, + cancel: () => { + this.#closed = true; + this.#pending = []; + this.#resolvePull(); + }, }, - { highWaterMark: this.incomingHighWaterMark }, + // Keep the backlog here so the live policy counts only unread packets. + { highWaterMark: 0 }, ); this.writable = new WritableStream({ write: (chunk) => { // Oversized or unsupported datagrams are discarded, not errored: // the writable stays usable, matching unreliable-datagram semantics. - if (this.#maxDatagramSize > 0 && chunk.byteLength <= this.#maxDatagramSize) { - this.#send(chunk); - } + if (this.#maxDatagramSize > 0 && chunk.byteLength <= this.#maxDatagramSize) send(chunk); }, }); } + static { + makeDatagrams = (send) => new Datagrams(datagramsKey, send); + pushDatagram = (datagrams, data) => datagrams.#push(data); + setMaxDatagramSize = (datagrams, size) => { + datagrams.#maxDatagramSize = size; + }; + closeDatagrams = (datagrams, err) => datagrams.#close(err); + } + /** The largest payload a datagram can carry, or 0 before the peer allows any. */ get maxDatagramSize(): number { return this.#maxDatagramSize; } - /** Resolve the send-payload limit from the negotiated parameters. */ - setMaxDatagramSize(size: number): void { - this.#maxDatagramSize = size; + /** The live inbound queue limit; lowering it preserves already queued datagrams. */ + get incomingHighWaterMark(): number { + return this.#incomingHighWaterMark; + } + + set incomingHighWaterMark(value: number) { + if (typeof value !== "number") throw new TypeError("incomingHighWaterMark must be a number"); + if (Number.isNaN(value) || value < 0) throw new RangeError("incomingHighWaterMark must be nonnegative"); + this.#incomingHighWaterMark = Math.max(1, value); + } + + /** Inbound expiry is unsupported. */ + get incomingMaxAge(): number | null { + return null; + } + + set incomingMaxAge(value: number | null) { + if (value !== null) throw new DOMException("Datagram expiry is unsupported", "NotSupportedError"); + } + + /** The outbound queue limit cannot be changed. */ + get outgoingHighWaterMark(): number { + return 1024; } - /** Deliver an inbound datagram to the reader, dropping it if the queue is full. */ - push(data: Uint8Array): void { - // `desiredSize` is null once the readable is closed/errored (e.g. a datagram - // arriving in a WS message the read loop delivers just after the session - // closed); enqueue would throw, so drop silently — matching Rust's try_send. - if (this.#incoming.desiredSize === null || this.#incoming.desiredSize <= 0) { - return; // reader is behind or gone — shed load + set outgoingHighWaterMark(value: number) { + if (value !== 1024) throw new DOMException("Outbound queue policy is unsupported", "NotSupportedError"); + } + + /** Outbound expiry is unsupported. */ + get outgoingMaxAge(): number | null { + return null; + } + + set outgoingMaxAge(value: number | null) { + if (value !== null) throw new DOMException("Datagram expiry is unsupported", "NotSupportedError"); + } + + #push(data: Uint8Array): void { + if (this.#closed) return; + if (this.#pullResolve) { + this.#incoming.enqueue(data); + this.#resolvePull(); + } else if (this.#pending.length < this.#incomingHighWaterMark) { + this.#pending.push(data); } - this.#incoming.enqueue(data); } - /** Close the inbound readable when the session ends. */ - close(err?: Error): void { - try { - if (err) this.#incoming.error(err); - else this.#incoming.close(); - } catch {} + #resolvePull(): void { + const resolve = this.#pullResolve; + this.#pullResolve = undefined; + resolve?.(); + } + + #close(err?: Error): void { + if (this.#closed) return; + this.#closed = true; + if (err) { + this.#pending = []; + this.#incoming.error(err); + } else if (this.#pending.length === 0) { + this.#incoming.close(); + } + this.#resolvePull(); } } @@ -586,8 +642,12 @@ export default class Session implements WebTransport { readonly incomingUnidirectionalStreams: ReadableStream>; #incomingUnidirectionalQueue: IncomingStreamQueue>; + readonly #datagrams = makeDatagrams((data) => this.#sendDatagram(data)); + /** Unreliable datagrams sent and received as QMux DATAGRAM frames. */ - readonly datagrams = new Datagrams((data) => this.#sendDatagram(data)); + get datagrams(): WebTransportDatagramDuplexStream { + return this.#datagrams; + } // Flow control state #config: Required; @@ -966,7 +1026,7 @@ export default class Session implements WebTransport { if (frameSize > this.#ourParams.maxDatagramFrameSize) { throw new Error("received a DATAGRAM larger than our advertised max_datagram_frame_size"); } - this.datagrams.push(frame.data); + pushDatagram(this.#datagrams, frame.data); } else if (frame.type === "ping_request") { // Draft-02: request sequence numbers must strictly increase. if (this.#version === "qmux-02") { @@ -1021,7 +1081,7 @@ export default class Session implements WebTransport { // varint sized for `cap`. Subtracting it keeps the frame within the limit. const overhead = BigInt(1 + VarInt.from(cap).size()); const payload = cap > overhead ? cap - overhead : 0n; - this.datagrams.setMaxDatagramSize(Number(payload)); + setMaxDatagramSize(this.#datagrams, Number(payload)); } // Credit streams created before params arrived. Only qmux-02 requires the @@ -1894,7 +1954,7 @@ export default class Session implements WebTransport { // app-initiated close leaves `#closeReason` unset, so the datagram // readable closes cleanly instead of erroring, matching the incoming // stream controllers below. - this.datagrams.close(this.#closeReason); + closeDatagrams(this.#datagrams, this.#closeReason); for (const c of this.#sendStreams.values()) { try { c.error(this.#closed); diff --git a/quest/m1/api-audit/qmux-datagrams.md b/quest/m1/api-audit/qmux-datagrams.md index 14c8ec327a8..481c0af0ade 100644 --- a/quest/m1/api-audit/qmux-datagrams.md +++ b/quest/m1/api-audit/qmux-datagrams.md @@ -15,42 +15,29 @@ qmux crate. ## Plan -Decided 2026-10-27 from the release-to-main API audit (maintainer picked each -option): +Implementation checkpoint 2026-10-29: -- Today ([js/qmux/src/session.ts](/js/qmux/src/session.ts) `Datagrams`): - `incomingHighWaterMark` is copied into the readable's `highWaterMark` at - construction, so a later assignment does nothing. The audit reproduced - `incomingHighWaterMark = 1` still queueing two packets. The other three - fields are never read. No consumer in this repository or moq.pro sets any - of them, and nothing outside qmux imports `Datagrams`, `push`, or - `setMaxDatagramSize`. -- **Live high-water mark, refuse the rest** (chosen over implementing all - four, which adds an age-stamped inbound queue and an outbound queue with no - consumer, and over refusing all four, which drops a cheap live-media - control). `push` drops once the queue length reaches the current - `incomingHighWaterMark`. Count the queue yourself instead of relying on the - stream's fixed `desiredSize`. Each of the other three becomes an accessor - that throws `NotSupportedError` for a non-default value and accepts the - default, so code written for the native interface that never changes them - keeps working. -- The high-water mark setter follows the WebTransport draft: `NaN` or a - negative value throws `RangeError`, and a value below 1 is stored as 1, so - no assignment can disable dropping or drop everything. Lowering it applies - to later pushes; datagrams already queued stay until read. -- **The DOM type is the public view** (chosen over a new qmux-owned - interface). Stop exporting `Datagrams` from - [js/qmux/src/index.ts](/js/qmux/src/index.ts). Declare `Session.datagrams` - as `WebTransportDatagramDuplexStream`. The restriction must hold at - runtime, not only in the types: `push`, the size update, and `close` - become `#` private members that the session reaches through module-private - functions assigned in a `static {}` block (the `Origin` pattern, as in - [no constructible internal handles](/quest/m1/api-audit/internal-constructors.md)), - with a private constructor. -- Tests: a lowered high-water mark sheds later overflow, a raised one admits - more, `NaN` and negative values throw, reads drain and cancel the readable - cleanly after a change, and each refused setter throws while its default - is accepted. +- The live inbound high-water mark, unsupported-policy refusal, and DOM-only + public/runtime view are implemented in JS QMux. The internal class has a + private constructor and runtime construction guard; only module-private + functions can deliver packets, update negotiated size, or end the receive + side. No expiry or outbound-queue machinery was added. +- Reproduced the original live-policy failures before changing production + code. All 233 QMux tests now pass, including live lower/raise behavior, + backlog retention, draining, pending reads, cancellation, malformed policy + input, refused setters, failure, and runtime privacy. +- Package type-check, build/publint, emitted-declaration consumer checks, + updated API report, and the receive-backlog benchmark pass. Local + self-review found no remaining QMux finding. +- The full `quest gate just ci` attempt failed because the local mbx Cargo + shim reports `Argument list too long (os error 7)`. This prevents the WASM + build selected for JS dependents and the unrelated Rust test-build lint + regression from running. Other completed lanes passed. Do not change JS + QMux to work around this tool-launch failure. +- Remaining: rerun the full local gate in a working build environment, + resolve relevant failures and review findings, then delete this quest and + its links and mark the PR ready. Keep the PR a draft until that validation + is complete. Do not merge, enqueue, or wait for online checks or reviews. Public API: breaking in `@moq/qmux` (the `Datagrams` export and its mutators go, and three setters now throw). The PR's Impact bullet says: stop From 81714866775f20707462044eb31b34cde48a4753 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 30 Oct 2026 22:19:52 -0700 Subject: [PATCH 3/3] fix(qmux): run the datagram backlog bench nightly and finish the quest Register js/qmux/bench/datagrams.ts as `just js qmux-datagrams-bench` and in the Nightly JS group, and name its column `us_per_read` so the bench report recognizes the unit. Delete the finished qmux-datagrams quest and its link. Co-Authored-By: Claude Opus 5.5 --- js/justfile | 5 +++ js/qmux/bench/datagrams.ts | 2 +- quest/m1/api-audit/README.md | 1 - quest/m1/api-audit/qmux-datagrams.md | 46 ---------------------------- sh/gh/nightly.sh | 1 + 5 files changed, 7 insertions(+), 48 deletions(-) delete mode 100644 quest/m1/api-audit/qmux-datagrams.md diff --git a/js/justfile b/js/justfile index 00e472c7231..8dbdeca2157 100644 --- a/js/justfile +++ b/js/justfile @@ -78,6 +78,11 @@ qmux-record-bench: bun install --frozen-lockfile bun qmux/bench/record.ts +# Sweep QMux datagram receive-queue draining over backlog size (median of 7 runs). +qmux-datagrams-bench: + bun install --frozen-lockfile + bun qmux/bench/datagrams.ts + # Sweep CMAF fragment decode over mdat bytes x declared sample count, including a hostile count. cmaf-bench: bun install --frozen-lockfile diff --git a/js/qmux/bench/datagrams.ts b/js/qmux/bench/datagrams.ts index 5542e1f70d9..527736ade55 100644 --- a/js/qmux/bench/datagrams.ts +++ b/js/qmux/bench/datagrams.ts @@ -49,7 +49,7 @@ async function measure(backlog: number): Promise { return elapsed; } -console.log("backlog,median_us_per_read"); +console.log("backlog,us_per_read"); for (const backlog of [1, 32, 1024, 16384]) { const samples: number[] = []; for (let run = 0; run < 7; run++) samples.push(await measure(backlog)); diff --git a/quest/m1/api-audit/README.md b/quest/m1/api-audit/README.md index 37e07504fdf..1e7c19cd44d 100644 --- a/quest/m1/api-audit/README.md +++ b/quest/m1/api-audit/README.md @@ -75,7 +75,6 @@ Rejected in planning: - [Two broadcast resolutions](/quest/m1/api-audit/resolve/README.md) - Rust, JS, and the bindings resolve a broadcast with `request(path, epoch)` or `follow(path, epoch)`, and every racy two-step caller is gone - [Demand is wanted, everywhere](/quest/m1/api-audit/wanted.md) - every `used`/`unused` pair becomes `wanted()` and `wanted_changed()`, and unused ones go -- [QMux datagrams obey or refuse their policy](/quest/m1/api-audit/qmux-datagrams.md) - `Session.datagrams` is the DOM interface, its high-water mark is live, and the inert settings throw - [No constructible internal handles](/quest/m1/api-audit/internal-constructors.md) - `Rendition`, `Lister`, `Arrivals`, and e2ee's generations get private constructors, and a lint rule stops new ones - [moq-congestion's first-publish names](/quest/m1/api-audit/congestion-names.md) - `bbr3::Config`, `cubic::Config`, `Metrics`, `Factory`, and no `into_any` diff --git a/quest/m1/api-audit/qmux-datagrams.md b/quest/m1/api-audit/qmux-datagrams.md deleted file mode 100644 index 481c0af0ade..00000000000 --- a/quest/m1/api-audit/qmux-datagrams.md +++ /dev/null @@ -1,46 +0,0 @@ -# [S] QMux datagrams obey or refuse their policy - -## Goal - -`@moq/qmux` `Session.datagrams` is typed as the browser's -`WebTransportDatagramDuplexStream` and nothing more. Its policy fields either -take effect or refuse loudly. `incomingHighWaterMark` limits every push after -it is set. Setting `incomingMaxAge` or `outgoingMaxAge` to anything -other than `null`, or changing `outgoingHighWaterMark`, throws. Applications can -no longer construct a `Datagrams`, inject inbound packets, overwrite the -negotiated size limit, or close the receive side. - -Non-goals: implementing datagram expiry or an outbound queue, and the Rust -qmux crate. - -## Plan - -Implementation checkpoint 2026-10-29: - -- The live inbound high-water mark, unsupported-policy refusal, and DOM-only - public/runtime view are implemented in JS QMux. The internal class has a - private constructor and runtime construction guard; only module-private - functions can deliver packets, update negotiated size, or end the receive - side. No expiry or outbound-queue machinery was added. -- Reproduced the original live-policy failures before changing production - code. All 233 QMux tests now pass, including live lower/raise behavior, - backlog retention, draining, pending reads, cancellation, malformed policy - input, refused setters, failure, and runtime privacy. -- Package type-check, build/publint, emitted-declaration consumer checks, - updated API report, and the receive-backlog benchmark pass. Local - self-review found no remaining QMux finding. -- The full `quest gate just ci` attempt failed because the local mbx Cargo - shim reports `Argument list too long (os error 7)`. This prevents the WASM - build selected for JS dependents and the unrelated Rust test-build lint - regression from running. Other completed lanes passed. Do not change JS - QMux to work around this tool-launch failure. -- Remaining: rerun the full local gate in a working build environment, - resolve relevant failures and review findings, then delete this quest and - its links and mark the PR ready. Keep the PR a draft until that validation - is complete. Do not merge, enqueue, or wait for online checks or reviews. - -Public API: breaking in `@moq/qmux` (the `Datagrams` export and its mutators -go, and three setters now throw). The PR's Impact bullet says: stop -importing `Datagrams` and use `session.datagrams.readable`, `.writable`, and -`.maxDatagramSize`; the removed mutators have no application replacement. -Wire: none. diff --git a/sh/gh/nightly.sh b/sh/gh/nightly.sh index 7f8bc0d4698..db7b4898cbe 100755 --- a/sh/gh/nightly.sh +++ b/sh/gh/nightly.sh @@ -141,6 +141,7 @@ case "$1" in done javascript catalog just js catalog-bench javascript qmux-record just js qmux-record-bench + javascript qmux-datagrams just js qmux-datagrams-bench javascript cmaf just js cmaf-bench javascript arrivals just js arrivals-bench javascript p2p just js p2p-bench