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
8 changes: 4 additions & 4 deletions doc/.vitepress/drafts.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -128,20 +128,20 @@ describe("tables render as tables", () => {

const rendered = html(page as DraftPage);

// The Bidirectional Streams table: one header, seven body rows, each
// The Bidirectional Streams table: one header, eight body rows, each
// separated by a kramdown rule in the source. Cells carry the source's
// alignment, so match around the style attribute.
const header = /<th[^>]*>Stream<\/th>/.exec(rendered);
expect(header).not.toBeNull();

for (const stream of ["Announce", "Subscribe", "Fetch", "Probe", "Goaway", "Track", "Auth"]) {
for (const stream of ["Announce", "Subscribe", "Fetch", "Probe", "Goaway", "Track", "Auth", "Tracks"]) {
expect(rendered).toMatch(new RegExp(`<td[^>]*>${stream}</td>`));
}

// One header row plus seven body rows, in a single table.
// One header row plus eight body rows, in a single table.
const start = rendered.lastIndexOf("<table", header?.index);
const rows = rendered.slice(start).split("</table>")[0];
expect(rows.match(/<tr>/g) ?? []).toHaveLength(8);
expect(rows.match(/<tr>/g) ?? []).toHaveLength(9);
});
});

Expand Down
9 changes: 9 additions & 0 deletions doc/concept/moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,15 @@ always a prefix. A service that serves only some of the paths beneath it
refuses the rest as they are requested. Announcements are hints; the request is
what decides.

Inside a broadcast, a reader can list its tracks (moq-lite-07, Rust only so
far): each track with its fixed properties, a synced mark, then tracks as they
come and go. Listing is discovery, not delivery: subscribe to each track you
want, and its groups still cached upstream reach you late. A broadcast lists
the tracks its publisher creates, never one served only on request, and a path
served under a prefix claim has nothing to list. Like announcements, a relay
syncs on what it holds now, so a fresh relay syncs empty and its upstream's
tracks follow.

Each route carries the chain of relay identities it passed through, which is
how forwarding loops are caught, and a cost, which is how a subscriber picks
among several routes to the same broadcast. It may also carry a
Expand Down
2 changes: 2 additions & 0 deletions drafts/draft-lcurley-moq-ietf.md
Original file line number Diff line number Diff line change
Expand Up @@ -208,6 +208,8 @@ A receiver refuses such a track as {{moqt}} ingress does, with an unsupported ex
The receiver parses the keys inside the Immutable Properties from its value, which a relay MUST NOT restate as mutable.
It SHOULD read them from the value when needed rather than hold them beside it, as a list of IDs can cost several times the value.

A TRACKS_ADD ({{moql}} Tracks Stream) embeds TRACK_INFO without TRACK_PROPERTIES, so when the extension is negotiated a subscriber MUST NOT skip the Track Stream for a track it learned from a listing.


# Datagrams {#datagrams}
When the extension is negotiated, a DATAGRAM carries a Datagram State after its Group Sequence.
Expand Down
90 changes: 89 additions & 1 deletion drafts/draft-lcurley-moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -396,6 +396,8 @@ There's a 1-byte STREAM_TYPE at the beginning of each stream.
| ------- | ------------- | ----------- |
| 0x7 | Auth | Either |
| ------- | ------------- | ----------- |
| 0x8 | Tracks | Subscriber |
| ------- | ------------- | ----------- |

### Announce
A subscriber can open an Announce Stream to discover routes matching a prefix.
Expand Down Expand Up @@ -552,6 +554,39 @@ If FRAME messages cannot be decoded against the cached TRACK_INFO, the subscribe

Because a subscriber cannot parse buffered group frames until TRACK_INFO arrives, the publisher SHOULD prioritize TRACK_INFO ahead of group data on the connection.

### Tracks {#tracks-stream}
A subscriber opens a Tracks Stream (0x8) to list the Tracks of one Broadcast.
A listing is discovery, not delivery: the subscriber SUBSCRIBEs to each Track it wants as usual, and a Track's groups reach a late SUBSCRIBE from the publisher's cache while they are retained.

The subscriber sends a [TRACKS](#tracks) message naming the broadcast path and Epoch.
The publisher replies with listing events, then FINs the stream once the Broadcast ends, or resets it on error:

- [TRACKS_ADD](#tracks-add): a Track is listed, with its TRACK_INFO.
- [TRACKS_REMOVE](#tracks-remove): a listed Track no longer is.
- [SYNCED](#synced): every Track this hop listed when the stream opened, and still lists, has been sent.

A Broadcast lists the Tracks its publisher produces.
A Track the publisher serves only on request, such as any name a transcoder answers for, is never listed, and listing never creates one.
A removal promises only that the Track is no longer listed; a SUBSCRIBE for its name MAY still succeed.
A Track listed again under a removed name is the same Track: within one Broadcast a name always means the same content.

The listing is relative to this hop: a relay answers with the Tracks it currently holds and never waits on its upstream, so a relay without a listing of its own sends SYNCED at once and its upstream's Tracks follow as live TRACKS_ADD.
A relay SHOULD answer every listing of a Broadcast from one upstream Tracks Stream.
A subscriber SHOULD hold at most one Tracks Stream per Broadcast, since each costs the publisher the whole listed set.
A publisher keeps only the newest Tracks Stream per Broadcast on a session and resets any older one with CANCELLED, rather than refusing the newer: a subscriber that stops listing and lists again can open the new stream before the publisher sees the old one close.

The publisher keeps a pending queue per stream, keyed by Track name in the order the changes happened.
A removal of a Track the subscriber has not been sent cancels its add, and a removal followed by an add of a name it was sent collapses in place into that removal then that add, so a stalled subscriber costs the names it was sent plus the listed set.
The publisher MUST send SYNCED exactly once: the first time that queue drains, or after it has sent N events, whichever comes first, where N is the queue's length when the stream opened.
A removal of a Track already sent MAY precede SYNCED.

The subscriber MUST close the session with a PROTOCOL_VIOLATION on a TRACKS_ADD for a name already listed on the stream, a TRACKS_REMOVE for a name not listed, a second SYNCED, or an unknown event type.
A FIN before SYNCED means the Broadcast ended.
On a FIN, a relay ends the listings it answers from that stream, even before the Broadcast's retraction arrives.
A publisher MUST reset a Tracks Stream with NOT_FOUND when the route it would serve the path from covers it by a shorter prefix: a route claims capability, not inventory, so it names no Broadcast to list.
A subscriber MAY skip the Track Stream for a Track it learned from TRACKS_ADD, since the properties are the same immutable ones.
Each listed Track a subscriber holds counts against its bound on announcements (see [Resource Exhaustion](#resource-exhaustion)); past it, the subscriber resets the stream rather than hold more.

### Probe
A subscriber opens a Probe Stream (0x4) to measure, and optionally increase, the available bitrate of the connection.
The publisher advertises its Probe level in SETUP (see [Probe Parameter](#probe-parameter)): None, Report (measure only), or Increase (measure and actively probe).
Expand Down Expand Up @@ -977,7 +1012,8 @@ SYNCED Message {
~~~

SYNCED has no body and assigns no Announce ID.
A second SYNCED on the same stream, or a stream ending before SYNCED, is a PROTOCOL_VIOLATION.
A second SYNCED on the same stream is a PROTOCOL_VIOLATION.
An Announce Stream ending before SYNCED is a PROTOCOL_VIOLATION; a Tracks Stream FIN before SYNCED means the Broadcast ended (see [Tracks](#tracks-stream)).


## ANNOUNCE_START {#announce-start}
Expand Down Expand Up @@ -1309,6 +1345,57 @@ Joins coalesce until the requested group arrives.
A relay preserves the ratio and evaluates joins against its own cache, forwarding demand in SUBSCRIBE_UPDATE.
Versions before lite-07 omit Refresh and Wanted Group; a Track received on those versions never refreshes.

## TRACKS {#tracks}
TRACKS is sent by a subscriber to list a Broadcast's Tracks.
It is the first message on a Tracks Stream (0x8).

~~~
TRACKS Message {
Message Length (i)
Broadcast Path (s)
Epoch (b)
}
~~~

**Broadcast Path**:
The path of the Broadcast to list.

**Epoch**:
The publisher instance the subscriber expects, as in [TRACK](#track).
The listing is pinned to the instance that answers it and ends with that instance.

## TRACKS_ADD {#tracks-add}
A publisher sends TRACKS_ADD on a Tracks Stream when a Track is listed.

~~~
TRACKS_ADD Message {
Type (i) = 0x0
Message Length (i)
Track Name (s)
Track Info (..)
}
~~~

**Track Name**:
The name of the Track, unique among the Tracks listed on the stream.

**Track Info**:
A [TRACK_INFO](#track-info) message, with its own Message Length, as a Track Stream would answer for the Track.

## TRACKS_REMOVE {#tracks-remove}
A publisher sends TRACKS_REMOVE on a Tracks Stream when a listed Track is no longer listed.

~~~
TRACKS_REMOVE Message {
Type (i) = 0x1
Message Length (i)
Track Name (s)
}
~~~

**Track Name**:
The name a TRACKS_ADD on the stream listed.

## SUBSCRIBE_OK {#subscribe-ok}
A SUBSCRIBE_OK message confirms a subscription and resolves its absolute start position.
It is the first message the publisher sends on the Subscribe Stream, once the start position is known.
Expand Down Expand Up @@ -1639,6 +1726,7 @@ The `Message Length` describes the payload size on the wire.

## moq-lite-07

- Added the Tracks Stream (0x8) with TRACKS, TRACKS_ADD, TRACKS_REMOVE, and SYNCED: a subscriber lists one Broadcast's Tracks, each with its TRACK_INFO, then SUBSCRIBEs to those it wants. A relay answers at once with what it holds. Older versions reset the stream type.
- Added TRACK_INFO `Refresh` and SUBSCRIBE_UPDATE `Wanted Group`, carrying ratio-based refresh demand through relays.

- Replaced ANNOUNCE_OK Active Count with an ordered, empty SYNCED event (0x4), marking the initial set without retaining routes that end before delivery.
Expand Down
5 changes: 3 additions & 2 deletions quest/m1/archive/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,8 @@ archive (per-track `.timeline.z` records named by the catalog's root
- **Discovery is pull**, decided 2026-10-19 in place of SUBSCRIBE_ALL's push:
ANNOUNCE finds the broadcasts under a prefix, a moq-lite TRACKS request
lists each broadcast's tracks as they appear, and the archive SUBSCRIBEs per
track, gating the lite-07 cut ([TRACKS](/quest/m1/archive/tracks.md)).
track, gating the lite-07 cut (`broadcast::Consumer::tracks` in Rust;
[TRACKS in js/net](/quest/m1/archive/tracks-js.md)).
moq-transport answers SUBSCRIBE_TRACKS through the same hook and learns an
IETF peer's tracks with a FORWARD=0 SUBSCRIBE_TRACKS
([SUBSCRIBE_TRACKS](/quest/m1/archive/subscribe-tracks.md)). Rejected:
Expand Down Expand Up @@ -83,7 +84,7 @@ from a host. Each child fixes the stale docs it touches.

## Required

- [TRACKS](/quest/m1/archive/tracks.md) - a moq-lite-07 request lists a broadcast's tracks with their TRACK_INFO, marks when it is synced, and names removed tracks, for the subscriber to SUBSCRIBE per track, and relays fan it out from one upstream request
- [TRACKS in js/net](/quest/m1/archive/tracks-js.md) - `@moq/net` lists a broadcast's tracks over lite-07's Tracks Stream and answers listings of its own broadcasts, mirroring Rust
- [Archive producer](/quest/m1/archive/producer.md) - `archive::Producer` stores every matching broadcast as duration-cut per-track objects keyed by group and pts, recording gaps instead of stalling, with an optional DVR mode
- [Archive consumer](/quest/m1/archive/consumer.md) - `archive::Consumer` serves a stored prefix as a broadcast from its key listing, and `moq export/import archive` use the new pair
- [Catalog HLS field](/quest/m1/archive/catalog-hls.md) - the root `archive` section is gone; an opt-in per-rendition `hls` field marks each aligned HLS segment's first group and pts and declares its nominal duration
Expand Down
6 changes: 1 addition & 5 deletions quest/m1/archive/producer.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Decided by the maintainer on 2026-10-17 (see the

- **Input.** One producer records every broadcast under a prefix as it
appears: ANNOUNCE finds each broadcast announced at its own path,
[TRACKS](/quest/m1/archive/tracks.md) lists its tracks, and each track
TRACKS (`broadcast::Consumer::tracks`) lists its tracks, and each track
records through its own SUBSCRIBE. A covering-prefix route is capability,
not inventory, so broadcasts served under one on request without their own
announcement are not recorded, and a TRACKS refused with NOT_FOUND on an
Expand Down Expand Up @@ -152,10 +152,6 @@ mid-recording writing no marker.
Public API: `archive::Producer` and its config replace `Writer`, `Control`,
and the timeline-driven types. Wire: none.

## Required

- [TRACKS](/quest/m1/archive/tracks.md) - how it learns each broadcast's tracks

## Related

- [Archive consumer](/quest/m1/archive/consumer.md) - reads this layout back
7 changes: 2 additions & 5 deletions quest/m1/archive/subscribe-tracks.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@
## Goal

moq-net speaks moq-transport SUBSCRIBE_TRACKS (draft-18 on) in both
directions through the [TRACKS](/quest/m1/archive/tracks.md) model hook,
directions through the TRACKS model hook (`broadcast::Consumer::tracks`
and `broadcast::Lister`),
instead of refusing it with NOT_SUPPORTED:

- **Inbound.** A moq-transport subscriber's SUBSCRIBE_TRACKS lists every
Expand Down Expand Up @@ -244,7 +245,3 @@ Public API: none beyond the TRACKS hook. Wire: moq-transport support for an
existing message, a FORWARD=0 PUBLISH held as a listing entry and resumed
for data, and an
inbound listing that answers FORWARD=1 with skips rather than data.

## Required

- [TRACKS](/quest/m1/archive/tracks.md) - the model hook this maps onto
38 changes: 38 additions & 0 deletions quest/m1/archive/tracks-js.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# [M] TRACKS in js/net

## Goal

`@moq/net` speaks the moq-lite-07 Tracks Stream (0x8) that Rust already
speaks, with the same behavior and mirrored names:

- **Listing.** A broadcast consumer lists its tracks (Rust
`broadcast::Consumer::tracks`): each listed track with its info, one
`synced` event, then adds and removals until the broadcast ends. Over a
session it opens one TRACKS per broadcast however many readers list it,
syncs its readers at once, and forwards the peer's tracks as live adds.
- **Answering.** A session answers a peer's TRACKS for a broadcast it
publishes with the tracks its producer created (never one served only on
request), using the per-reader queue and SYNCED rule the draft specifies.
- **Refusals.** Older versions reset the stream type, as now. A covering
prefix route answers NOT_FOUND. A listing past the session's announce cap
is reset.

## Plan

The wire and the Rust model landed first; read the Tracks section of
`drafts/draft-lcurley-moq-lite.md` and mirror `rs/moq-net/src/model/listing.rs`
(the queue keyed by name in insertion order, where an unread add and removal
cancel and a removal then re-add of a seen name collapses in place) and
`rs/moq-net/src/lite/tracks.rs` (the encoding: TRACKS_ADD 0x0 with an
embedded TRACK_INFO, TRACKS_REMOVE 0x1, SYNCED 0x4).

`js/net/src/lite/malformed.test.ts` still treats type 8 as unknown on
lite-07; it becomes a real stream here.

Test the same cases as Rust: snapshot then SYNCED, SYNCED after N events
under churn, a stalled reader's bounded queue, removal before SYNCED, a
dynamic-only track never listed, the broadcast ending the listing, and
`just test interop --all` against the Rust side in both directions.

Public API: a track-listing method on the JS broadcast consumer, named like
Rust's. Wire: none new.
Loading
Loading