diff --git a/quest/m1/api-audit/README.md b/quest/m1/api-audit/README.md index bc0254a9327..11766b5445d 100644 --- a/quest/m1/api-audit/README.md +++ b/quest/m1/api-audit/README.md @@ -77,6 +77,9 @@ Rejected in planning: - [Bindings default to zero max delay](/quest/m1/api-audit/binding-max-delay.md) - a no-argument subscription skips superseded groups in every binding, as Rust, JS, and Python do, and no subscriber limit is asked for explicitly - [Demand is wanted, everywhere](/quest/m1/api-audit/wanted.md) - every `used`/`unused` pair becomes `wanted()` and `wanted_changed()`, and unused ones go - [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 +- [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..6584d982780 --- /dev/null +++ b/quest/m1/api-audit/congestion-names.md @@ -0,0 +1,39 @@ +# [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. +- moq-quic's `transport::Config` already nests the controller factory + (`congestion: Arc`, defaulting to + `congestion::Bbr3Config`); rename its uses, its tests, and its bench to the + new names here. + +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. diff --git a/quest/m1/api-audit/internal-constructors.md b/quest/m1/api-audit/internal-constructors.md new file mode 100644 index 00000000000..dd53225a4bc --- /dev/null +++ b/quest/m1/api-audit/internal-constructors.md @@ -0,0 +1,46 @@ +# [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 failing at runtime (`Lister` +throws inside its constructor, `Rendition` 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. +- 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 new file mode 100644 index 00000000000..14c8ec327a8 --- /dev/null +++ b/quest/m1/api-audit/qmux-datagrams.md @@ -0,0 +1,59 @@ +# [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 + +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 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. + +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/quest/m1/api-audit/resolve/README.md b/quest/m1/api-audit/resolve/README.md index 83b04f632fb..8dfaf5375d2 100644 --- a/quest/m1/api-audit/resolve/README.md +++ b/quest/m1/api-audit/resolve/README.md @@ -51,6 +51,7 @@ Wire: none. ## Required - [Bindings request and follow](/quest/m1/api-audit/resolve/bindings.md) - moq-ffi, the C ABI, and every wrapper mirror `request` and `follow` with an optional epoch +- [The player takes any read-side origin](/quest/m1/api-audit/resolve/watch-origin.md) - `@moq/watch`'s `Player` and `Broadcast` accept a read-only `Origin.Consumer` as well as a `Table` - [The carla demo pins its driver epoch](/quest/m1/api-audit/resolve/callers.md) - the demo's driver watcher requests each run pinned to its announced epoch ## Related diff --git a/quest/m1/api-audit/resolve/watch-origin.md b/quest/m1/api-audit/resolve/watch-origin.md new file mode 100644 index 00000000000..553aaa0e2f9 --- /dev/null +++ b/quest/m1/api-audit/resolve/watch-origin.md @@ -0,0 +1,22 @@ +# [S] The player takes any read-side origin + +## Goal + +`@moq/watch`'s `Player` and `Broadcast` accept a read-only `Origin.Consumer` +as well as an `Origin.Table`, so `new Player({ origin: producer.consume() })` +type-checks. + +## Plan + +Decided 2026-10-27 (maintainer): both take a structural read-side origin type +(`closed`, `discovery`, `request`, `follow`, `announced`), not +`Origin.Table`. Today the call above 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`. Do not add an adapter +or a parallel player class. + +The `request(path, { announced })` calls already map onto `follow` and +`request` ([moq-dev/moq#7173](https://github.com/moq-dev/moq/pull/7173)). + +Public API: widens `@moq/watch`'s accepted input; not breaking. +Wire: none. diff --git a/quest/m1/quic-api/README.md b/quest/m1/quic-api/README.md index e5c32cd9da5..1ea034586b4 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`, which has landed.