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
2 changes: 1 addition & 1 deletion doc/concept/standard.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ maps everything else to "not supported" or a harmless equivalent. The
subset drops. What a peer actually observes against this implementation:

- **Pull.** Subscribers ask. Single-track `PUBLISH` offers are declined, unless they answer our `SUBSCRIBE_TRACKS` (below); announce a namespace and serve the resulting subscriptions. Announcements go out unsolicited. A client asks only for the prefixes its readers watch, and a server or relay link for every prefix it may discover. Rust never holds two overlapping requests at a peer that did not declare solicit: a broader one replaces the narrower ones once they are closed. The solicit `SETUP` option makes us wait to be asked. Without it, a draft 16+ peer also gets each match as a `NAMESPACE` on its `SUBSCRIBE_NAMESPACE` stream, so it hears the namespace twice. We send `PUBLISH` only to answer a `SUBSCRIBE_TRACKS` (below): on drafts 16 and 17 a `SUBSCRIBE_NAMESPACE` asking only for `PUBLISH` is refused, one asking for both gets only `NAMESPACE`, and any other Subscribe Options value closes the session.
- **`SUBSCRIBE_TRACKS` lists, it never pushes.** On draft 18 and later, it lists every track of every broadcast under its prefix, later ones included. With `FORWARD=0`, each track gets a paused `PUBLISH` carrying its Track Properties, and an error `PUBLISH_DONE` once the track is no longer listed, never `TRACK_ENDED`, since the track may go on elsewhere. A `REQUEST_UPDATE` with `FORWARD=1` resumes one, served from the cache like a `SUBSCRIBE` with the update's filter and answered with `LARGEST_OBJECT`; `FORWARD=0` pauses it again. Each paused `PUBLISH` opens only as the peer's stream credit admits it, so a peer that grants none holds none. A listing that omits `FORWARD` or sets it to 1 asks for every track's objects: from draft 19 each track gets `PUBLISH_SKIPPED`, and the subscriber `SUBSCRIBE`s to what it wants; draft 18 has no such skip, so the request is refused with `NOT_SUPPORTED`. A prefix overlapping another listing gets `PREFIX_OVERLAP`, a `TRACK_PROPERTY_FILTER` gets `NOT_SUPPORTED`, and a `REQUEST_UPDATE` on the listing itself ends it. On draft 18, a `SUBSCRIBE` to a track we `PUBLISH`ed gets `DUPLICATE_SUBSCRIPTION`. Cancelling the listing stops new `PUBLISH`es, while those sent live on. A broadcast is listed only while our publish grant covers it, from scratch once it does. Rust sends it upstream for a listing (below); JavaScript does not.
- **`SUBSCRIBE_TRACKS` lists, it never pushes.** On draft 18 and later, it lists every track of every broadcast under its prefix, later ones included. With `FORWARD=0`, each track gets a paused `PUBLISH` carrying its Track Properties, and a `PUBLISH_DONE` once the track is no longer listed: `TRACK_ENDED` if it finished, even just before its broadcast ended, and an error otherwise, since the track may go on elsewhere. A `REQUEST_UPDATE` with `FORWARD=1` resumes one, served from the cache like a `SUBSCRIBE` with the update's filter and answered with `LARGEST_OBJECT`; `FORWARD=0` pauses it again. Each paused `PUBLISH` opens only as the peer's stream credit admits it, so a peer that grants none holds none. A listing that omits `FORWARD` or sets it to 1 asks for every track's objects: from draft 19 each track gets `PUBLISH_SKIPPED`, and the subscriber `SUBSCRIBE`s to what it wants; draft 18 has no such skip, so the request is refused with `NOT_SUPPORTED`. A prefix overlapping another listing gets `PREFIX_OVERLAP`, a `TRACK_PROPERTY_FILTER` gets `NOT_SUPPORTED`, and a `REQUEST_UPDATE` on the listing itself ends it. On draft 18, a `SUBSCRIBE` to a track we `PUBLISH`ed gets `DUPLICATE_SUBSCRIPTION`. Cancelling the listing stops new `PUBLISH`es, while those sent live on. A broadcast is listed only while our publish grant covers it, from scratch once it does. Rust sends it upstream for a listing (below); JavaScript does not.
- **A Rust TRACKS listing sends `SUBSCRIBE_TRACKS` upstream, only on demand.** Listing a broadcast from a moq-transport peer on draft 18 and later sends `SUBSCRIBE_TRACKS` with `FORWARD=0` while someone lists it, never on connect, announce, or subscribe, so a peer that refuses, resets, or ignores it affects only that listing. Before draft 18 the listing is refused as unsupported. Each listed track's paused `PUBLISH` is its upstream copy, which a reader resumes rather than subscribing again. Only a `PUBLISH_DONE` with `TRACK_ENDED` removes a listed track, and it lists as finished; any other end, including the error our own answerer sends for a track that left unfinished, fails the listing, and readers list again.
- **History is one group.** In Rust, Object ID gaps must be marked by Prior Object ID Gap properties for a group to be fetchable. A `FETCH` returns one group from the cache, or on drafts 14 through 19 the saved prefix of the group a new subscription just joined. A range of groups is refused, as is a draft 20+ `LOCATION_FILTER` that ends at Largest Object rather than an absolute End Location. On drafts 14 through 19, `FETCH_OK` End Object 0 covers the entire End Group, matching the request; Rust also accepts the legacy answer naming the next group with Object 0. On draft 20 and later, `FETCH_OK`'s End Location is the requested end, capped at Largest Object: a range holding no objects gets an empty fetch stream, and only a start past Largest Object is refused, with `INVALID_RANGE`. A relay's copy with no upstream subscription can't know Largest Object short of the track's end, so it echoes the requested end instead. JavaScript publishing refuses every `FETCH`. Datagrams are never fetchable. A Rust reader that only fetches learns the track from `TRACK_STATUS` instead of subscribing, so a finished track stays fetchable; draft 17 still subscribes, since its `TRACK_STATUS` answer cannot say whether the track is timed, and so does a reader whose publisher refuses `TRACK_STATUS` as `NOT_SUPPORTED`.
- **Compression.** Rust peers on draft 17 and later exchange compressed tracks when both offer the [Flate extension](/draft/moq-flate). Older peers receive one shared inflated copy. A publisher that seals the compression declaration makes that fallback unavailable: an incompatible peer is refused, preserving the sealed metadata. JavaScript does not offer the IETF extension.
Expand Down
2 changes: 1 addition & 1 deletion js/net/src/broadcast.ts
Original file line number Diff line number Diff line change
Expand Up @@ -147,7 +147,7 @@ async function requested(state: BroadcastState): Promise<track.Request | undefin
function closeState(state: BroadcastState) {
if (state.closed.peek() !== undefined) return;
state.closed.set(null);
state.listing.detach(null);
state.listing.close();
for (const cleanup of state.demands.values()) cleanup();
for (const request of state.pending) request.reject();
state.requested.mutate((requests) => {
Expand Down
14 changes: 13 additions & 1 deletion js/net/src/ietf/publisher.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2540,7 +2540,19 @@ export class Publisher {
reading ??= listing.next().then((event): Woken => ({ kind: "track", event }));
waits.push(reading);
}
const woken = await untilAborted(race(waits), hold.signal);
let woken: Woken;
try {
woken = await untilAborted(race(waits), hold.signal);
} catch (err) {
// A closed broadcast's listing has already ended, after the tracks that left
// before it, so it is read to that end whatever withdrew the broadcast: a
// PUBLISH whose track finished ends with TRACK_ENDED. Nothing more goes out.
if (source.closed.peek() === undefined) throw err;
pending.clear();
unstage();
reading ??= listing.next().then((event): Woken => ({ kind: "track", event }));
woken = await reading;
}
if (woken.kind === "changed") continue;
if (woken.kind === "failed") {
console.debug(`listed broadcast=${namespace}: PUBLISH stream did not open`, woken.err);
Expand Down
69 changes: 61 additions & 8 deletions js/net/src/ietf/subscribe_tracks.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -233,31 +233,84 @@ for (const version of drafts) {
const clock = new Manual();
const installed = clock.install();
using _installed = { [Symbol.dispose]: () => installed.close() };
const fx = fixture(version);
const broadcast = fx.origin.createBroadcast(Path.from("room/live"));
broadcast.announce();
const track = broadcast.createTrack("video");
const listing = await fx.list();
await ok(listing, version);
// Spied before listing, since the PUBLISH may go out before the listing's OK is read.
// Restored only once the test is done: `Message.write` reads `writer.write` before
// awaiting its frame, so restoring mid-write would drop a concurrent write on the stale spy.
const resume = Promise.withResolvers<void>();
let holding = false;
const write = Writer.prototype.write;
const held = spyOn(Writer.prototype, "write").mockImplementation(async function (this: Writer, chunk) {
await write.call(this, chunk);
if (chunk[0] !== Publish.id) return;
held.mockRestore();
if (holding || chunk[0] !== Publish.id) return;
holding = true;
await resume.promise;
});
using _held = { [Symbol.dispose]: () => held.mockRestore() };
const fx = fixture(version);
const broadcast = fx.origin.createBroadcast(Path.from("room/live"));
broadcast.announce();
const track = broadcast.createTrack("video");
const listing = await fx.list();
await ok(listing, version);
const { stream } = await fx.offered(false);
track.close();
broadcast.removeTrack("video");
await clock.advance(Nano.zero);
expect(holding).toBe(true);
resume.resolve();
await publishOk(stream, version);
expect(await stream.reader.u53()).toBe(PublishDone.id);
const done = await PublishDone.decode(stream.reader, version);
expect(done.statusCode).toBe(PublishDoneStatus.TRACK_ENDED);
});

// A broadcast closing right after a track finished ends that track's PUBLISH with TRACK_ENDED,
// removed first or not and answered or not, while a track left unfinished still ends in error:
// PUBLISH_DONE once answered, a reset before.
for (const remove of [false, true]) {
for (const answer of [true, false]) {
const name = `remove=${remove} answer=${answer}`;
test(`a clean end keeps its finishes, ${name} (${version})`, async () => {
const clock = new Manual();
const installed = clock.install();
using _installed = { [Symbol.dispose]: () => installed.close() };
const fx = fixture(version);
const broadcast = fx.origin.createBroadcast(Path.from("room/live"));
broadcast.announce();
const video = broadcast.createTrack("video");
broadcast.createTrack("audio");
const listing = await fx.list();
await ok(listing, version);
const published = new Map<string, Stream>();
for (let i = 0; i < 2; i++) {
const { stream, publish } = await fx.offered(answer);
published.set(publish.trackName, stream);
}
await clock.advance(Nano.zero);
video.close();
if (remove) broadcast.removeTrack("video");
broadcast.close();
await clock.advance(Nano.zero);
const videoStream = published.get("video");
const audioStream = published.get("audio");
if (!videoStream || !audioStream) throw new Error("missing PUBLISH");
if (!answer) await publishOk(videoStream, version);
expect(await videoStream.reader.u53()).toBe(PublishDone.id);
expect((await PublishDone.decode(videoStream.reader, version)).statusCode).toBe(
PublishDoneStatus.TRACK_ENDED,
);
if (!answer) {
await expect(audioStream.reader.u53()).rejects.toThrow();
return;
}
expect(await audioStream.reader.u53()).toBe(PublishDone.id);
expect((await PublishDone.decode(audioStream.reader, version)).statusCode).toBe(
PublishDoneStatus.INTERNAL_ERROR,
);
});
}
}

test(`track listing rejects overlapping prefixes (${version})`, async () => {
const fx = fixture(version);
const broadcast = fx.origin.createBroadcast(Path.from("room/live"));
Expand Down
58 changes: 58 additions & 0 deletions js/net/src/listing.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -196,6 +196,64 @@ test("the broadcast ending ends the listing", async () => {
expect(() => consumer.tracks()).toThrow("broadcast is closed");
});

// A clean end reports each track that left before it, and how, but not one the reader never
// saw; an error ends at once.
test("a clean end follows the removals before it", async () => {
const broadcast = new BroadcastProducer();
const a = broadcast.createTrack("a");
broadcast.createTrack("b");
const live = broadcast.createTrack("live");
const tracks = list(broadcast);
expect(await tracks.drain()).toEqual(["+a", "+b", "+live", "synced"]);
a.close();
broadcast.removeTrack("a");
broadcast.removeTrack("b");
broadcast.createTrack("unseen");
live.close();
broadcast.close();
expect(await tracks.drain()).toEqual(["~a", "-b", "~live", "end"]);

// The producer's finished track is what a handler's answer of its name served.
const both = new BroadcastProducer();
const handler = wireOf(both).lister();
handler.add("a", { priority: 0 });
handler.synced();
const own = both.createTrack("a");
const served = list(both);
expect(await served.drain()).toEqual(["+a", "synced"]);
own.close();
both.close();
expect(await served.drain()).toEqual(["~a", "end"]);

// A reader that closes itself reads nothing more, even what was queued before the end.
const closing = new BroadcastProducer();
const gone = closing.createTrack("gone");
const reader = list(closing);
expect(await reader.drain()).toEqual(["+gone", "synced"]);
gone.close();
closing.removeTrack("gone");
closing.close();
reader.tracks.close();
expect(await reader.drain()).toEqual(["end"]);

for (const abort of [false, true]) {
const answered = new BroadcastProducer();
const lister = wireOf(answered).lister();
const reader = list(answered);
lister.add("up", { priority: 0 });
lister.synced();
expect(await reader.drain()).toEqual(["+up", "synced"]);
lister.finish("up");
if (abort) {
lister.abort(new NotFound("broadcast"));
expect(await reader.drain()).toEqual([`error: ${StreamCode.NotFound}`]);
} else {
lister.end();
expect(await reader.drain()).toEqual(["~up", "end"]);
}
}
});

test("a closed listing reads nothing more, and leaving a loop early closes it", async () => {
const broadcast = new BroadcastProducer();
broadcast.createTrack("a");
Expand Down
28 changes: 24 additions & 4 deletions js/net/src/listing.ts
Original file line number Diff line number Diff line change
Expand Up @@ -119,8 +119,14 @@ class Queue {
}

next(): TracksEvent | undefined {
if (this.end !== undefined) {
if (this.end) throw this.end;
if (this.end) throw this.end;
if (this.end === null) {
// A clean end still reports each track that left before it, and how; an add the
// reader never read is dropped.
for (const [name, pending] of this.pending) {
this.pending.delete(name);
if (pending.kind !== "add") return { kind: pending.finished ? "finished" : "removed", name };
}
return undefined;
}
if (!this.synced && this.bound !== undefined && (this.bound === 0 || this.pending.size === 0)) {
Expand Down Expand Up @@ -229,8 +235,9 @@ export class Listing {
return queue;
}

/** A reader left. A replaced or ended one already did. */
/** A reader left, so it reads nothing more. A replaced or ended one already did. */
release(queue: Queue, owner?: object) {
Comment thread
kixelated marked this conversation as resolved.
Resolved
queue.pending.clear();
if (queue.detached) return;
queue.finish(null);
this.#readers.delete(queue);
Expand Down Expand Up @@ -312,6 +319,18 @@ export class Listing {
this.#answered = false;
}

/**
* The broadcast ended: so does every listing of it, first unlisting each of its producer's tracks
* that finished. A handler's answer of the same name does not keep it live, since the producer's
* track is what served it.
*/
close() {
for (const [name, entry] of [...this.#live]) {
if (entry.own && finished(entry.own)) this.#remove(name, true);
}
this.detach(null);
}

/** End every reader with `end` and detach them. */
detach(end: Error | null) {
for (const queue of this.#readers) queue.finish(end);
Expand All @@ -336,7 +355,8 @@ export function listTracks(listing: Listing, owner?: object): Tracks {
* The tracks a broadcast lists, from its consumer's `tracks()`.
*
* Reports every track listed when it was created, then `synced`, then each change as it
* happens, until the broadcast ends. Listing a broadcast never requests a track: subscribe to
* happens, until the broadcast ends: a clean end comes after each track that left before it, and
* a track still listed then ends unfinished. Listing a broadcast never requests a track: subscribe to
* each listed one through the consumer's `track(name)`.
*
* @public
Expand Down
28 changes: 28 additions & 0 deletions js/net/src/resume.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2595,6 +2595,34 @@ test.each([
}
});

// A source that finished a track and closed just before the front concluded ended its listing
// after that finish, so the front's listing ends after it too.
test("a concluded front's listing keeps its closed source's finishes", async () => {
const front = new Front();
const a = new BroadcastProducer();
const from = a.consume();
const answer = wireOf(from).lister();
answer.add("seq", { priority: 0 });
answer.add("live", { priority: 0 });
answer.synced();
front.serve(from);
const tracks = front.consumer.tracks();
try {
for (const event of [{ kind: "added", name: "seq" }, { kind: "added", name: "live" }, { kind: "synced" }])
expect(await tracks.next()).toMatchObject(event);
answer.finish("seq");
a.close();
front.conclude();
expect(await tracks.next()).toMatchObject({ kind: "finished", name: "seq" });
expect(await tracks.next()).toBeUndefined();
} finally {
tracks.close();
answer.close();
front.consumer.close();
a.close();
}
});

test("only delivery codes are a route failing", () => {
// Mirrors `only_delivery_codes_are_a_route_failing` in rs/moq-net/src/model/resume.rs.
const delivery = [0x0, 0x1, 0x3, 0x4, 0x31];
Expand Down
37 changes: 27 additions & 10 deletions js/net/src/resume.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1348,6 +1348,22 @@ export class Front {
listing?.reader?.close();
listing = undefined;
};
const read = (reader: Tracks): Promise<{ event?: TracksEvent; err?: Error }> =>
reader.next().then(
(event) => ({ event }),
(err: unknown) => ({ err: err instanceof Error ? err : new Error(String(err)) }),
);
// Forwarded as the source reported it, finished or not.
const unlist = (
listed: Set<string>,
stale: Set<string>,
event: { kind: "removed" | "finished"; name: string },
) => {
stale.delete(event.name);
if (!listed.delete(event.name)) return;
if (event.kind === "finished") lister.finish(event.name);
else lister.remove(event.name);
};
try {
for (;;) {
if (closed.peek() !== undefined) return;
Expand All @@ -1360,7 +1376,15 @@ export class Front {
continue;
}
if (this.#concluded) {
// No route will serve it again, so nothing more will be listed.
// No route will serve it again, so nothing more will be listed. A source that
// closed ended its listing after the tracks it finished last: those go first.
while (listing?.reader && listing.source?.from.closed.peek() !== undefined) {
const { event } = await (listing.next ?? read(listing.reader));
listing.next = undefined;
if (!event) break;
if (event.kind === "removed" || event.kind === "finished")
unlist(listing.listed, listing.stale, event);
}
stop();
lister.end();
continue;
Expand Down Expand Up @@ -1390,10 +1414,7 @@ export class Front {
await wait();
continue;
}
listing.next ??= reader.next().then(
(event) => ({ event }),
(err: unknown) => ({ err: err instanceof Error ? err : new Error(String(err)) }),
);
listing.next ??= read(reader);
const result = await race([listing.next, wait().then(() => undefined)]);
if (!result) continue;
listing.next = undefined;
Expand All @@ -1420,11 +1441,7 @@ export class Front {
lister.add(event.name, event.info);
}
} else if (event.kind === "removed" || event.kind === "finished") {
// Forwarded as the source reported it, finished or not.
listing.stale.delete(event.name);
if (!listing.listed.delete(event.name)) continue;
if (event.kind === "finished") lister.finish(event.name);
else lister.remove(event.name);
unlist(listing.listed, listing.stale, event);
} else {
// What the new source still lacks at its SYNCED is gone.
for (const name of listing.stale) {
Expand Down
Loading
Loading