Repository navigation
quest: plan the API audit's honesty findings #7000
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
9cc05b7
quest: plan the API audit's honesty findings
kixelated 037b96c
quest: verify api-audit fixes against emitted types and live reads
kixelated 1449c22
quest: settle datagram setter bounds, runtime privacy, and watch callers
kixelated 55e29eb
quest: a lowered datagram mark limits later pushes
kixelated 92580c5
Merge main into quest-plan/api-audit-honesty
kixelated File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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<dyn congestion::ControllerFactory + ...>`, 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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
|
coderabbitai[bot] marked this conversation as resolved.
Resolved
|
||
| 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. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.