Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions quest/m1/api-audit/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
39 changes: 39 additions & 0 deletions quest/m1/api-audit/congestion-names.md
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.
46 changes: 46 additions & 0 deletions quest/m1/api-audit/internal-constructors.md
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.
59 changes: 59 additions & 0 deletions quest/m1/api-audit/qmux-datagrams.md
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
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
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
Comment thread
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.
1 change: 1 addition & 0 deletions quest/m1/api-audit/resolve/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
22 changes: 22 additions & 0 deletions quest/m1/api-audit/resolve/watch-origin.md
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.
3 changes: 2 additions & 1 deletion quest/m1/quic-api/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
Loading