Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
31a87f4
chore(quest): claim quest/m1/datagram-tracks/js.md
kixelated Nov 4, 2026
15108c7
feat(net)!: split JavaScript datagram tracks
kixelated Nov 4, 2026
69a46c9
Merge remote-tracking branch 'origin/main' into quest/m1/datagram-tra…
kixelated Nov 4, 2026
2512a1c
fix(net): release closed datagram waiters and preserve relayed sequences
kixelated Nov 4, 2026
664c708
style(net): format datagram info wait
kixelated Nov 4, 2026
3d9a023
fix(net): prioritize each modern datagram send queue
kixelated Nov 4, 2026
92e4d21
test(net): identify datagram queues independently of request order
kixelated Nov 4, 2026
e2871e2
fix(net): hold legacy stream demand for datagram readers
kixelated Nov 4, 2026
397efa2
fix(net): discard cancelled legacy datagram lookups before stream acc…
kixelated Nov 4, 2026
dfbc295
docs(net): describe datagram source lifetime
kixelated Nov 4, 2026
9489083
Merge remote-tracking branch 'origin/main' into HEAD
kixelated Nov 4, 2026
3d4dd09
fix(net): skip closed datagram requests when creating a track
kixelated Nov 4, 2026
d3516c2
fix(net): recheck datagram priority after each DATAGRAMS_UPDATE write
kixelated Nov 4, 2026
1eaec20
Merge remote-tracking branch 'origin/main' into iterate-7846
kixelated Nov 4, 2026
c0501f6
Merge remote-tracking branch 'origin/main' into HEAD
kixelated Nov 4, 2026
d90756d
Merge remote-tracking branch 'origin/main' into iterate-7846
kixelated Nov 4, 2026
a83f3e2
fix(net): isolate datagram readers and drop sends after cancellation
kixelated Nov 4, 2026
6e93762
fix(net): race the datagram close handle directly
kixelated Nov 4, 2026
0d5a793
Merge remote-tracking branch 'origin/main' into iterate-7846
kixelated Nov 4, 2026
12f80db
Merge remote-tracking branch 'origin/main' into HEAD
kixelated Nov 4, 2026
44797bb
fix(net): fail a datagram request whose consumer closed with an error
kixelated Nov 4, 2026
3d32604
Merge remote-tracking branch 'origin/main' into iterate-7846
kixelated Nov 4, 2026
77b8074
fix(crypto): wait for a datagram track before appending in its test
pullfrog[bot] Nov 5, 2026
9293fc1
Merge remote-tracking branch 'origin/main' into iterate-7846
kixelated Nov 5, 2026
b87db78
Merge remote-tracking branch 'origin/main' into iterate-7846
kixelated Nov 5, 2026
eebeed2
Merge base and reconcile snapshot latest test
Nov 5, 2026
d0ea90d
Merge branch 'base' into pr-7846
Nov 5, 2026
6b9824d
fix(quest): reconcile completed JS datagram prerequisite
Nov 5, 2026
7851e52
Merge base and preserve both net migration entries
Nov 5, 2026
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: 2 additions & 1 deletion doc/concept/moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -449,7 +449,8 @@ datagrams and `audio` as streams are two independent tracks. Nothing on the
wire says which kind a name is: the application knows from its catalog or by
convention, so a broadcast's track listing never includes a datagram track. In
Rust, `broadcast.create_datagrams(name, info)` publishes one and
`broadcast.datagrams(name)` reads it.
`broadcast.datagrams(name)` reads it. In JavaScript use
`broadcast.createDatagrams(name, info)` and `broadcast.datagrams(name)`.

A datagram subscription is live from when it starts: it has no ranges, order,
or max delay, only a priority, which a subscriber can change. A datagram still
Expand Down
2 changes: 1 addition & 1 deletion doc/concept/standard.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ subset drops. What a peer actually observes against this implementation:
- **One `SETUP` credential**, forwarded to the [auth server](/bin/relay/auth#the-contract) unverified. A second `SETUP` token closes the session. We advertise no token cache, so an alias reference in `SETUP` closes it with `PROTOCOL_VIOLATION`, one on a request with `UNKNOWN_AUTH_TOKEN_ALIAS`, and a registration on a request with `AUTH_TOKEN_CACHE_OVERFLOW`. Where the Rust side authorizes the peer or verifies tokens, each distinct request token is verified once while any open request on that session names it, and its grant authorizes only requests naming it, even where that authorization already covers it; it never widens the session. It is refused with `NOT_SUPPORTED` when nothing verifies it, when it is empty, or when its Token Type is anything but 0 (out of band). A side that does neither, JavaScript included, ignores the token. Rust refuses a request carrying more than one distinct token with `NOT_SUPPORTED`, since it verifies one; JavaScript, which verifies none, ignores them all. A token-authorized `SUBSCRIBE` still stays within the grant the peer gave us. A token-authorized `PUBLISH_NAMESPACE` needs a grant covering everything beneath the namespace, and the tracks we subscribe under it rely on that announce instead of our limit, ending with it. An update on a token-authorized request moves it to the token it carries; the old token ends with its last naming request. A request is admitted by the session or by a token for good, so an update naming a token on one the session admitted is refused with `NOT_SUPPORTED`. A token-less `PUBLISH_NAMESPACE` our limit does not cover is refused `UNAUTHORIZED`, and one the limit stops covering ends; the publisher re-announces once it widens. Expiry or revocation ends every request naming that token. The relay reports the lease end to its auth server, and a later request naming the token verifies it again. A refused renewal ends only that request. Rust and JavaScript send the token a route names (`Route::auth`) on its `PUBLISH_NAMESPACE`, and swapping it renews the request with `REQUEST_UPDATE`; the inline `NAMESPACE` that answers a solicited `SUBSCRIBE_NAMESPACE` carries no token. A token added to a reconnecting connection's auth handle rides every session it makes, so the announcement keeps it across a reconnect; one added to a single session's handle ends with that session. Rust honors a token on any supported request; discovery reveals only paths it grants, and a joining `FETCH` keeps following its subscription. A request repeating a token is refused with `MALFORMED_AUTH_TOKEN`. The negotiated [MoQ Auth extension](/concept/moq-lite#authorization) accepts additional session tokens in band.
- **Pause delivery.** `FORWARD=0` on a `SUBSCRIBE` or its update drops the subscription, closing its data streams and holding nothing upstream, while the request and its slot stay. `FORWARD=1` subscribes again as a new `SUBSCRIBE` with the same filter would, so nothing carries across the pause: its `REQUEST_OK` names the live edge it joined at. A paused update may change only priority and max age.
- **Refused, not fatal.** A legal request this stack does not serve is rejected on its own and the session stays up: `SUBSCRIBE_TRACKS`, multi-group `FETCH`, and joining requests reaching before the joined group get `NOT_SUPPORTED`. Range Filters get `INVALID_FILTER` from draft 20 because the advertised filter limit is zero. From draft 20, namespaces whose first tuple field is exactly `.` or `.session` get `DOES_NOT_EXIST` before application lookup; other dot prefixes still reach the application. Subscription updates accept priority, negotiated subscriber max age, and delivery timeouts. Rust also carries range changes, keeps bounded subscriptions updatable, renews request tokens, and judges `NEW_GROUP_REQUEST` as a join (see dynamic groups below). From draft 20, a wider or historical fill fails on its separate fetch stream while its subscription stays open; a largest-group fill hands its head to the live subgroup tail. Other supported-but-unimplemented preferences end that subscription; a `TRACK_PROPERTY_FILTER` there closes the session with `PROTOCOL_VIOLATION`, since it belongs only to `SUBSCRIBE_TRACKS`. A namespace update may change its prefix; suffixes after the acknowledgement are relative to that new prefix.
- **Objects and datagrams.** Only subgroup 0 is accepted: a stream for any other subgroup, whether its header gives the ID or takes it from the first Object ID, is stopped and the session stays up. Rust relays preserve Object IDs, gaps, object properties, FIRST\_OBJECT, and END\_OF\_GROUP status objects between moq-transport peers for subgroup 0, including across a moq-lite-07 hop between two relays that negotiate the [ietf](/draft/moq-ietf) extension. Plain Rust readers and moq-lite peers without the extension see consecutive frames. Rust drops every OBJECT\_DATAGRAM, since a moq-lite track takes either streams or datagrams and Rust does not yet map a [datagram track](/concept/moq-lite#datagrams) onto moq-transport; JavaScript supports only normal datagrams at Object ID 0. A malformed datagram closes the session. A relayed Timestamp leaves in the units the downstream response declares, and is dropped where it declares none, as for a plain frame; an immutable one that would change or vanish is refused. On a timed track the frame holds each object's time, so a mutable Timestamp that only repeats the immutable one is not restated; a status object has no frame, so it keeps its Timestamp among its properties. Only property 0x10 is read as a Timestamp. Property 0x06 stays opaque and keeps its value regardless of timestamp units; it is dropped between draft 18 and later drafts, or refused when immutable, because draft 20 assigns it to SUBGROUP\_DELIVERY\_TIMEOUT. A status object carrying properties is refused. A `FETCH` has no status objects, so its response ends at the last frame. A group cannot resume across route changes by frame ordinal once Object IDs skip ahead of the ordinals on either route; recovery refuses it instead of splicing different objects.
- **Objects and datagrams.** Only subgroup 0 is accepted: a stream for any other subgroup, whether its header gives the ID or takes it from the first Object ID, is stopped and the session stays up. Rust relays preserve Object IDs, gaps, object properties, FIRST\_OBJECT, and END\_OF\_GROUP status objects between moq-transport peers for subgroup 0, including across a moq-lite-07 hop between two relays that negotiate the [ietf](/draft/moq-ietf) extension. Plain Rust readers and moq-lite peers without the extension see consecutive frames. Rust and JavaScript drop every OBJECT\_DATAGRAM until they map a [datagram track](/concept/moq-lite#datagrams) onto moq-transport. A malformed datagram closes the session. A relayed Timestamp leaves in the units the downstream response declares, and is dropped where it declares none, as for a plain frame; an immutable one that would change or vanish is refused. On a timed track the frame holds each object's time, so a mutable Timestamp that only repeats the immutable one is not restated; a status object has no frame, so it keeps its Timestamp among its properties. Only property 0x10 is read as a Timestamp. Property 0x06 stays opaque and keeps its value regardless of timestamp units; it is dropped between draft 18 and later drafts, or refused when immutable, because draft 20 assigns it to SUBGROUP\_DELIVERY\_TIMEOUT. A status object carrying properties is refused. A `FETCH` has no status objects, so its response ends at the last frame. A group cannot resume across route changes by frame ordinal once Object IDs skip ahead of the ordinals on either route; recovery refuses it instead of splicing different objects.
- **Dynamic groups.** A track advertises `DYNAMIC_GROUPS` when its publisher sets a refresh ratio, and a track received with `DYNAMIC_GROUPS` gets a ratio of 0. A `NEW_GROUP_REQUEST` counts as one more subscriber joining, which a `SUBSCRIBE` already is: it asks for a new group only when the newest group's bytes after its first frame exceed the ratio times the first frame. Joins coalesce until the asked-for group arrives. A Rust relay sends `NEW_GROUP_REQUEST` upstream, on the `SUBSCRIBE` or in a `REQUEST_UPDATE`, once a join wants a group past the newest it holds; a relay holding nothing yet asks for none. On a track without a ratio, an update carrying one ends the subscription with `UPDATE_FAILED`. A moq-lite-07 hop (`moq-lite-07-wip`, opt-in) carries the same demand natively: the ratio in `TRACK_INFO` and the asked-for group in `SUBSCRIBE_UPDATE`. Earlier moq-lite versions carry neither, so a track received over one never refreshes.
- **Priority.** Higher is served first. This stack's priorities run from -128 to 127 with 0 unset, and go out on the IETF wire, which ranks lower first, as `127 - priority`: an unset priority is IETF 127. An omitted subscriber or publisher priority reads as the drafts' default of IETF 128, one step below unset, so a relay forwards it unchanged. A relay's upstream subscription carries the highest priority its subscribers ask for and updates it as they come and go; its group order stays as the `SUBSCRIBE` asked, since no draft lets an update change it.
- **Size.** An object extension block larger than 64 KiB ends that subgroup stream. The session stays up. This cap is ours, not the draft's.
Expand Down
10 changes: 5 additions & 5 deletions drafts/draft-lcurley-moq-flate.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ Each subgroup is a separate DEFLATE stream: its object payloads share one window

The application decides which subgroups a track uses; a consumer knows which to expect and decodes each one's objects in order.

A datagram carries a group of one object, so it is a stream of its own: compressed alone, starting cold.
Datagram tracks are never compressed.

An object with no payload is skipped, neither advancing nor resetting the window.

Expand All @@ -77,7 +77,7 @@ The compression level is a publisher's choice; any conformant stream decodes.

# Declaring Compression {#declare}
The transport declares a track compressed, and gives each object's inflated size beside its compressed one.
{{moql}} does both from moq-lite-07: a Compression codec id in TRACK_INFO, and an Inflated Size on each FRAME and datagram.
{{moql}} does both from moq-lite-07: a Compression codec id in TRACK_INFO, and an Inflated Size on each FRAME.
A consumer MUST NOT infer compression from the payload: raw DEFLATE has no magic number, so a wrong guess yields plausible garbage.

A consumer MUST treat an object that inflates to more or less than its declared size as malformed, and abandon the subgroup.
Expand Down Expand Up @@ -109,7 +109,7 @@ Every Normal Object on a compressed track MUST carry it, including an empty payl
A plain track or a status object MUST NOT carry it.
It can appear in the mutable list or Immutable Properties, but MUST NOT appear more than once across them.
The base Object Payload Length remains the size of the compressed bytes.
The same rules apply to subgroup streams, FETCH streams, and datagrams.
The same rules apply to subgroup streams and FETCH streams.

A receiver MUST validate the declared size against the same resource limits as an uncompressed payload before admitting it, and MUST NOT allocate a buffer solely from that declaration.
Incremental inflate output is charged to the receiver's cache budget and shared across its plain readers.
Expand Down Expand Up @@ -150,9 +150,9 @@ It also requests these entries in the MOQ Properties registry, outside the appli
## Since draft-lcurley-moq-flate-00 (in progress)

- Negotiated FLATE signaling adds COMPRESSION and INFLATED_SIZE properties to MoQ Transport draft-18 and later; sealed declarations are forwarded unchanged or refused when incompatible.
- Compression is declared by the transport instead of the application: {{moql}} carries a Compression codec in TRACK_INFO and each object's Inflated Size on FRAME and datagrams.
- Compression is declared by the transport instead of the application: {{moql}} carries a Compression codec in TRACK_INFO and each object's Inflated Size on FRAME.
- A relay inflates for a peer whose transport does not declare compression.
- A datagram is compressed alone, as a stream of its own.
- Datagram tracks are not compressed and carry no Inflated Size.
- A consumer rejects an object that inflates to other than its declared size, or that ends in a final block.

# Acknowledgments
Expand Down
14 changes: 14 additions & 0 deletions js/crypto/MIGRATE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# Migrating @moq/crypto

## Unreleased

### Protected datagrams use their own tracks ([#7846](https://github.com/moq-dev/moq/pull/7846))

Call `E2EE.Broadcast.Producer.createDatagrams(semantic, info)` and
`E2EE.Broadcast.Consumer.datagrams(semantic)`. Their `E2EE.Datagram.Producer` and
`Consumer` use `append`, `insert`, and `recv` in place of the stream track's
`appendDatagram`, `insertDatagram`, and `recvDatagram`. A datagram's sequence is
independent of same-name groups; the existing separate cryptographic key domains
keep their nonces distinct. Stream authentication failures and lifecycle operations
no longer end the datagram track. Finish or abort its producer, and close its consumer,
independently.
15 changes: 14 additions & 1 deletion js/crypto/src/e2ee/broadcast.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,8 @@
*
* @module
*/
import type { Broadcast as NetBroadcast, Track as NetTrack } from "@moq/net";
import type { Broadcast as NetBroadcast, Datagram as NetDatagram, Track as NetTrack } from "@moq/net";
import type * as Datagram from "./datagram.ts";
import type * as Epoch from "./epoch.ts";
import type * as Generation from "./generation.ts";
import type * as Track from "./track.ts";
Expand Down Expand Up @@ -47,6 +48,12 @@ export class Producer {
return this.generation.produce(this.#inner.createTrack(name, info), semantic);
}

/** Create a protected datagram track in its own namespace and sequence space. */
async createDatagrams(semantic: string, info: Partial<NetDatagram.Info> = {}): Promise<Datagram.Producer> {
const name = await this.generation.name(semantic);
return this.generation.produceDatagrams(this.#inner.createDatagrams(name, info), semantic);
}

/** End the wrapped broadcast, as `@moq/net`'s `close` does. Idempotent. */
close(): void {
this.#inner.close();
Expand Down Expand Up @@ -80,6 +87,12 @@ export class Consumer {
return this.generation.consume(this.#inner.track(name).subscribe(subscription), semantic);
}

/** Read the protected datagram track under its semantic name, live from when that name resolves to its physical one. */
async datagrams(semantic: string): Promise<Datagram.Consumer> {
const name = await this.generation.name(semantic);
return this.generation.consumeDatagrams(this.#inner.datagrams(name), semantic);
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
}

/** Release the wrapped broadcast handle, as `@moq/net`'s `close` does. Idempotent. */
close(): void {
this.#inner.close();
Expand Down
Loading
Loading