From 9cc05b7c94c7f4695b851b91539296020fcb555a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 27 Oct 2026 21:41:24 -0700 Subject: [PATCH 1/4] quest: plan the API audit's honesty findings Plan QMux datagram policy, internal constructors, and moq-congestion naming as api-audit children, and fold the read-side Player input into the broadcast resolution quest. Co-Authored-By: Claude Opus 5.5 --- quest/m1/api-audit/README.md | 3 ++ quest/m1/api-audit/congestion-names.md | 42 ++++++++++++++++++ quest/m1/api-audit/internal-constructors.md | 42 ++++++++++++++++++ quest/m1/api-audit/qmux-datagrams.md | 47 +++++++++++++++++++++ quest/m1/api-audit/resolve.md | 7 +++ quest/m1/quic-api/README.md | 3 +- quest/m1/quic-api/config.md | 6 +-- 7 files changed, 146 insertions(+), 4 deletions(-) create mode 100644 quest/m1/api-audit/congestion-names.md create mode 100644 quest/m1/api-audit/internal-constructors.md create mode 100644 quest/m1/api-audit/qmux-datagrams.md diff --git a/quest/m1/api-audit/README.md b/quest/m1/api-audit/README.md index 5d3565b75ce..94afa7a762c 100644 --- a/quest/m1/api-audit/README.md +++ b/quest/m1/api-audit/README.md @@ -79,6 +79,9 @@ Rejected in planning: - [One meaning for Credential](/quest/m1/api-audit/dial-credential.md) - the internal dial type gets its own name in JS and moq-tokio, and the `Presented` alias goes - [One strict path rule](/quest/m1/api-audit/strict-paths.md) - `Relative` refuses empty segments, `Path` refuses non-canonical escapes, the error is `path::Error`, and auth mints only strict paths - [Unix sockets accept through the allowlist](/quest/m1/api-audit/unix-accept.md) - the public pre-allowlist `unix::Listener::accept` becomes crate-private +- [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` ## Related diff --git a/quest/m1/api-audit/congestion-names.md b/quest/m1/api-audit/congestion-names.md new file mode 100644 index 00000000000..edfec90cd5d --- /dev/null +++ b/quest/m1/api-audit/congestion-names.md @@ -0,0 +1,42 @@ +# [S] moq-congestion's first-publish names + +## Goal + +`moq-congestion` first publishes with namespaced names and no downcasting: +`bbr3::Config`, `cubic::Config`, `Metrics`, and `Factory`, with `Bbr3`, +`Cubic`, and `Unlimited` at the crate root, and no `Controller::into_any`. +Every caller in moq-quic, moq-tokio, moq-uring, and the benches uses the new +names. + +Non-goals: new controller signals or a controller framework, and +`clone_box`, which QUIC path migration needs. + +## Plan + +Decided 2026-10-27 from the release-to-main API audit (maintainer picked each +option): + +- The crate is still 0.1.0 and unpublished, and + [noq adopts moq-congestion](/quest/m2/noq-congestion.md) starts after the + m1 cut publishes it, so the rename costs one change now and nothing later. +- **Namespace** (chosen over keeping the quinn-style names that noq's + adapter would read more easily): make `bbr3` and `cubic` public modules + exporting `Config`. Rename `ControllerMetrics` to `Metrics` and + `ControllerFactory` to `Factory`. Keep `Bbr3`, `Cubic`, `Unlimited`, + `Controller`, `Packet`, and the event structs at the root. +- **Remove `into_any`**: its only callers are the moq-tokio tests in + `rs/moq-tokio/src/quic/backend.rs` that assert which controller a factory + built. Check the selection another way (such as observable behavior or + metrics) or drop an assertion that only restates the `match`. noq's adapter + keeps its own `into_any` on its side of the boundary. +- [The QUIC config](/quest/m1/quic-api/config.md) nests whatever names land + here in `transport::Config`. Whichever lands second adopts the other's + names. + +Public API: breaking in moq-congestion (unpublished) and in the moq-quic, +moq-tokio, and moq-uring re-exports or signatures that name these types. +Wire: none. + +## Related + +- [QUIC config](/quest/m1/quic-api/config.md) - nests the controller config these names define diff --git a/quest/m1/api-audit/internal-constructors.md b/quest/m1/api-audit/internal-constructors.md new file mode 100644 index 00000000000..58f52676786 --- /dev/null +++ b/quest/m1/api-audit/internal-constructors.md @@ -0,0 +1,42 @@ +# [S] No constructible internal handles + +## Goal + +No exported JS class can be built from its emitted declarations with +arguments that skip its factory. `new Rendition()`, `new Lister()`, and +`new Arrivals()` fail to type-check instead of producing a handle that +crashes on `close()`. A lint rule rejects any new `@internal` constructor. + +## Plan + +Decided 2026-10-27 from the release-to-main API audit (maintainer picked each +option): + +- The bug: `js/tsconfig.json` sets `stripInternal`, so an `@internal` + constructor disappears from the declaration. The class then shows an + implicit public zero-argument constructor. The audit reproduced + `new Rendition()` type-checking and then throwing `this.#close is not a + function`. Both are already on `release`. +- **Every instance**, published and private: + `Rendition` ([js/publish/src/rendition.ts](/js/publish/src/rendition.ts), + built by `Broadcast`), `Lister` + ([js/net/src/listing.ts](/js/net/src/listing.ts)), `Arrivals` + ([js/watch/src/arrivals.ts](/js/watch/src/arrivals.ts)), and the two + constructors in [js/e2ee/src/generation.ts](/js/e2ee/src/generation.ts) + (the package is private, but the same mistake stays fixed). +- **The fix is the `Origin` pattern** + ([js/net/src/origin.ts](/js/net/src/origin.ts)): a real `private + constructor` plus a module-level factory assigned in the class's `static {}` + block. A factory used from another module, such as `Rendition`'s from + `broadcast.ts`, must not escape through the package's `export *`. Put it in + a module the entry point does not re-export. Factories stay the only entry + point; documentation alone or another `@internal` tag does not prevent the + construction. +- **Guard**: a Biome GritQL plugin (Biome 2.5 is in use) registered in + `biome.jsonc` flags a `constructor` carrying an `@internal` JSDoc tag, so + `just check` fails on a recurrence. If Biome cannot see the JSDoc tag, + write a declaration test that asserts each exported class's constructor + arity. + +Public API: breaking only for code that called these constructors, which +always produced broken handles. Wire: none. diff --git a/quest/m1/api-audit/qmux-datagrams.md b/quest/m1/api-audit/qmux-datagrams.md new file mode 100644 index 00000000000..57d4958fa74 --- /dev/null +++ b/quest/m1/api-audit/qmux-datagrams.md @@ -0,0 +1,47 @@ +# [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` bounds the inbound queue +whenever 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 + +Decided 2026-10-27 from the release-to-main API audit (maintainer picked each +option): + +- 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 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` and keep the class in a private field + that the session's frame handling and parameter negotiation use. +- Tests: a lowered high-water mark sheds the overflow, a raised one admits + more, and each refused setter throws while its default is accepted. + +Public API: breaking in `@moq/qmux` (the `Datagrams` export and its mutators +go, and three setters now throw). The Impact bullet says to use +`session.datagrams` through the WebTransport interface. Wire: none. diff --git a/quest/m1/api-audit/resolve.md b/quest/m1/api-audit/resolve.md index 7cce21a65ce..e652759a5c1 100644 --- a/quest/m1/api-audit/resolve.md +++ b/quest/m1/api-audit/resolve.md @@ -45,6 +45,13 @@ and the bindings promote it as a top-level convenience. discovery is unavailable. `Producer.request`/`announced` pass-throughs stay only if `Table` needs them. moq.pro's five `{announced: true}` sites move to `follow`. +- Read-side input (decided 2026-10-27): `@moq/watch`'s `Player` and + `Broadcast` take a structural read-side origin type (`closed`, `discovery`, + `request`, `follow`, `announced`), not `Origin.Table`, so both `Table` and + a read-only `Origin.Consumer` satisfy it. Today + `new Player({ origin: producer.consume() })` fails to type-check only + because `Table` also requires `createBroadcast`. Do not add an adapter or a + parallel player class. - Bindings: `request_broadcast(path, epoch)` and `announced_broadcast(path, epoch)` map onto the two operations under the same names as Rust, and the Kotlin, Dart, Go, and Python top-level shortcuts follow. diff --git a/quest/m1/quic-api/README.md b/quest/m1/quic-api/README.md index ac112a18b76..1f92a2384a6 100644 --- a/quest/m1/quic-api/README.md +++ b/quest/m1/quic-api/README.md @@ -9,7 +9,8 @@ error type per direction, terminal operations that consume their handle, plain config structs, and no quinn compatibility baggage. Consumers lose the workarounds quinn's shape forced on them. -Non-goals: the congestion controller API (redesigned in another quest), a +Non-goals: the congestion controller API +([its names](/quest/m1/api-audit/congestion-names.md)), a buffer pool ([QUIC I/O boundary](/quest/m2/quic-io-boundary.md)), and the non-QUIC backends' move off `web_transport_trait` ([drop web-transport-trait](/quest/m1/drop-web-transport-trait.md)). diff --git a/quest/m1/quic-api/config.md b/quest/m1/quic-api/config.md index 38dec89c06b..e790e2bf395 100644 --- a/quest/m1/quic-api/config.md +++ b/quest/m1/quic-api/config.md @@ -74,9 +74,9 @@ connecting to only the first DNS answer, with their own congestion enum) go; moq-uring's tests, the bench, and moq-tokio's test use the driver's `connect` instead (maintainer, 2026-10-23). -Out of scope: the congestion controller API, which another quest is -redesigning (maintainer, 2026-10-23); nest whatever it lands in -`transport::Config`. +Out of scope: the congestion controller API (maintainer, 2026-10-23); nest +whatever names [congestion names](/quest/m1/api-audit/congestion-names.md) +lands in `transport::Config`. The Impact bullet says how to migrate in moq-quic, moq-tokio, moq-uring, and qmux; update moq-tokio's `quic::Config` resolution and moq-relay's limits. From 037b96c584f44a729b4c32f75eab51416c6f8389 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 27 Oct 2026 21:47:35 -0700 Subject: [PATCH 2/4] quest: verify api-audit fixes against emitted types and live reads Co-Authored-By: Claude Opus 5.5 --- quest/m1/api-audit/internal-constructors.md | 3 +++ quest/m1/api-audit/qmux-datagrams.md | 3 ++- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/quest/m1/api-audit/internal-constructors.md b/quest/m1/api-audit/internal-constructors.md index 58f52676786..88df3651269 100644 --- a/quest/m1/api-audit/internal-constructors.md +++ b/quest/m1/api-audit/internal-constructors.md @@ -37,6 +37,9 @@ option): `just check` fails on a recurrence. If Biome cannot see the JSDoc tag, write a declaration test that asserts each exported class's constructor arity. +- Verify against the emitted declarations, not the sources: a + `@ts-expect-error` fixture compiled against each package's built types + shows `new X()` no longer type-checks. Public API: breaking only for code that called these constructors, which always produced broken handles. Wire: none. diff --git a/quest/m1/api-audit/qmux-datagrams.md b/quest/m1/api-audit/qmux-datagrams.md index 57d4958fa74..d899ff19e34 100644 --- a/quest/m1/api-audit/qmux-datagrams.md +++ b/quest/m1/api-audit/qmux-datagrams.md @@ -40,7 +40,8 @@ option): as `WebTransportDatagramDuplexStream` and keep the class in a private field that the session's frame handling and parameter negotiation use. - Tests: a lowered high-water mark sheds the overflow, a raised one admits - more, and each refused setter throws while its default is accepted. + more, reads drain and cancel the readable cleanly after a change, and each + refused setter throws while its default is accepted. Public API: breaking in `@moq/qmux` (the `Datagrams` export and its mutators go, and three setters now throw). The Impact bullet says to use From 1449c220a224404a9debce8d8b42ee979b7928cb Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 27 Oct 2026 21:54:01 -0700 Subject: [PATCH 3/4] quest: settle datagram setter bounds, runtime privacy, and watch callers Co-Authored-By: Claude Opus 5.5 --- quest/m1/api-audit/internal-constructors.md | 5 +++-- quest/m1/api-audit/qmux-datagrams.md | 25 +++++++++++++++------ quest/m1/api-audit/resolve.md | 9 +++++--- 3 files changed, 27 insertions(+), 12 deletions(-) diff --git a/quest/m1/api-audit/internal-constructors.md b/quest/m1/api-audit/internal-constructors.md index 88df3651269..dd53225a4bc 100644 --- a/quest/m1/api-audit/internal-constructors.md +++ b/quest/m1/api-audit/internal-constructors.md @@ -4,8 +4,9 @@ No exported JS class can be built from its emitted declarations with arguments that skip its factory. `new Rendition()`, `new Lister()`, and -`new Arrivals()` fail to type-check instead of producing a handle that -crashes on `close()`. A lint rule rejects any new `@internal` constructor. +`new Arrivals()` fail to type-check instead of failing at runtime (`Lister` +throws inside its constructor, `Rendition` on `close()`). A lint rule +rejects any new `@internal` constructor. ## Plan diff --git a/quest/m1/api-audit/qmux-datagrams.md b/quest/m1/api-audit/qmux-datagrams.md index d899ff19e34..37d80dd3200 100644 --- a/quest/m1/api-audit/qmux-datagrams.md +++ b/quest/m1/api-audit/qmux-datagrams.md @@ -34,15 +34,26 @@ option): 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` and keep the class in a private field - that the session's frame handling and parameter negotiation use. -- Tests: a lowered high-water mark sheds the overflow, a raised one admits - more, reads drain and cancel the readable cleanly after a change, and each - refused setter throws while its default is accepted. + 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. Public API: breaking in `@moq/qmux` (the `Datagrams` export and its mutators -go, and three setters now throw). The Impact bullet says to use -`session.datagrams` through the WebTransport interface. Wire: none. +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/quest/m1/api-audit/resolve.md b/quest/m1/api-audit/resolve.md index e652759a5c1..314702bb107 100644 --- a/quest/m1/api-audit/resolve.md +++ b/quest/m1/api-audit/resolve.md @@ -49,9 +49,12 @@ and the bindings promote it as a top-level convenience. `Broadcast` take a structural read-side origin type (`closed`, `discovery`, `request`, `follow`, `announced`), not `Origin.Table`, so both `Table` and a read-only `Origin.Consumer` satisfy it. Today - `new Player({ origin: producer.consume() })` fails to type-check only - because `Table` also requires `createBroadcast`. Do not add an adapter or a - parallel player class. + `new Player({ origin: producer.consume() })` fails to type-check because + `Table` also requires `createBroadcast` and `requests`. Retype every + `Moq.Origin.Table` input in `js/watch/src/player.ts` and `broadcast.ts`, + and map `broadcast.ts`'s `origin.request(path, { announced })` calls: + `announced: true` becomes `follow`, `false` becomes `request`. Do not add + an adapter or a parallel player class. - Bindings: `request_broadcast(path, epoch)` and `announced_broadcast(path, epoch)` map onto the two operations under the same names as Rust, and the Kotlin, Dart, Go, and Python top-level shortcuts follow. From 55e29ebae1d53a2869e7c263bedb1d7bf0bf08b3 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 27 Oct 2026 21:55:32 -0700 Subject: [PATCH 4/4] quest: a lowered datagram mark limits later pushes Co-Authored-By: Claude Opus 5.5 --- quest/m1/api-audit/qmux-datagrams.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/quest/m1/api-audit/qmux-datagrams.md b/quest/m1/api-audit/qmux-datagrams.md index 37d80dd3200..14c8ec327a8 100644 --- a/quest/m1/api-audit/qmux-datagrams.md +++ b/quest/m1/api-audit/qmux-datagrams.md @@ -4,8 +4,8 @@ `@moq/qmux` `Session.datagrams` is typed as the browser's `WebTransportDatagramDuplexStream` and nothing more. Its policy fields either -take effect or refuse loudly. `incomingHighWaterMark` bounds the inbound queue -whenever it is set. Setting `incomingMaxAge` or `outgoingMaxAge` to anything +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.