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: 2 additions & 1 deletion doc/concept/standard.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,8 @@ 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. We never hold 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 peer also gets each match as a `NAMESPACE` on its `SUBSCRIBE_NAMESPACE` stream, so it hears the namespace twice. We never send `PUBLISH`.
- **We list no tracks by `PUBLISH`.** Rust and JavaScript refuse each `SUBSCRIBE_TRACKS` with `NOT_SUPPORTED`, and the session stays up. Our own peers list tracks over moq-lite instead.
- **A Rust TRACKS listing sends `SUBSCRIBE_TRACKS` upstream, only on demand.** Listing a broadcast from a moq-transport peer 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. 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 fails the listing, and readers list again. Our own moq-transport publishers refuse it, so a Rust listing of one fails.
- **History is served one group at a time.** Our moq-transport publishers answer a `FETCH` only within one group, a draft-18 joining `FETCH` for the subscription's current group head, and a draft 20+ fill for the largest group's head. Whole-group fetches wait for an open group to finish. Both implementations accept and ignore `FILL_TIMEOUT`, including zero. A JavaScript subscription joins at the current group: on draft 18 it fetches the group's head with a Relative Joining `FETCH`, and from draft 20 asks for it with a fill. Datagrams are never fetchable. Subscribers still request ranges upstream, one per run of missing groups; a third-party publisher can answer those ranges and mark their gaps. A Rust reader that only fetches learns the track from `TRACK_STATUS`, so a finished track stays fetchable; a reader whose publisher refuses `TRACK_STATUS` as `NOT_SUPPORTED` still subscribes.
- **History is served one group at a time.** Our moq-transport publishers answer a `FETCH` only within one group, a draft-18 joining `FETCH` for the subscription's current group head, and a draft 20+ fill for the largest group's head. Whole-group fetches wait for an open group to finish. Both implementations accept and ignore `FILL_TIMEOUT`, including zero. A JavaScript subscription joins at the current group: on draft 18 it fetches the group's head with a Relative Joining `FETCH`, and from draft 20 asks for it with a fill. Datagrams are never fetchable. Subscribers still request ranges upstream, one per run of missing groups; a third-party publisher can answer those ranges and mark their gaps. A Rust reader that only fetches learns the track from `TRACK_STATUS`, so a finished track stays fetchable; a refused `TRACK_STATUS` fails that reader's request, whatever the code, rather than falling back to a `SUBSCRIBE`.
- **A requester's FIN.** On draft 18 a requester finishing its stream cancels its request, except after `TRACK_STATUS`: nothing can follow it, so the FIN only ends the requester's input and the request is still answered. From draft 20 a FIN never cancels; a reset or `STOP_SENDING` does.
- **Compression.** Rust peers exchange compressed tracks when both offer the [Flate extension](/draft/moq-flate). Other 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.
- **Timing.** A track whose `SUBSCRIBE_OK` or `PUBLISH` declares no `TIMESCALE` is untimed. A `SUBSCRIBE` or `FETCH` with `INCLUDE_PROPERTIES=0` gets no `TIMESCALE` in its `SUBSCRIBE_OK` or `FETCH_OK`, so its objects go out unstamped. A Rust reader that never subscribed takes the units from `TRACK_STATUS`, and still asks for the properties whenever it subscribes to or fetches a timed track.
- **Strict SETUP and parameters.** Repeated unknown `SETUP` options, GREASE included, are accepted if well-formed; a repeated known option is rejected. A `GROUP_ORDER` other than Ascending (1) or Descending (2) closes the session. An unknown message parameter, or one defined only for another message, closes the session. Other malformed control input closes the session with the draft's code too, such as a server `SETUP` carrying `PATH` or `AUTHORITY`, a namespace field ending in `/` (it would map to a path with an empty segment), a request cut short by FIN, or a second `GOAWAY` on one stream; a first `GOAWAY` on a request stream is legal.
Expand Down
29 changes: 29 additions & 0 deletions js/net/src/ietf/publisher.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -218,6 +218,8 @@ function requestStream(version: IetfVersion) {
wire: () => new Reader(undefined, Uint8Array.from(written), version),
send: (bytes: Uint8Array) => input.enqueue(bytes),
cancel: () => input.error(new Error("request cancelled")),
/** FIN the request's side: the requester has nothing more to send. */
finish: () => input.close(),
/**
* End the request as `version` cancels one: by FIN through draft 18, and by a reset
* after.
Expand Down Expand Up @@ -286,6 +288,33 @@ test("TRACK_STATUS is answered on every draft without subscribing", async () =>
}
});

// A requester may FIN right after TRACK_STATUS, since nothing can follow it (moxygen does).
// That only ends its input, so the request is still answered, on draft 18 too.
test("TRACK_STATUS finished at once is answered on every draft", async () => {
for (const version of IETF_VERSIONS) {
const pair = createMockTransportPair(ALPNS[version]);
const session = new NativeSession(pair.server, version, true);
const { pub, origin } = publisher(pair.server, { session });
const requests = origin.requestsRoute(Path.from("room")).requested();

// The FIN arrives while the broadcast still resolves.
const { stream, wire, finish } = requestStream(version);
const task = pub.runTrackStatusRequest(trackStatus("room"), stream);
const pending = (await requests.next()).value;
if (!pending) throw new Error("no request for room");
finish();
const served = new BroadcastProducer();
served.createTrack("video");
hooks.acceptRequest(pending, served);
await task;
expect(await wire().u53()).toBe(TrackStatusOk.id);

await requests.return?.();
served.close();
origin.close();
}
});

// A track that has published nothing answers without LARGEST_OBJECT.
test("TRACK_STATUS for an empty track names no largest", async () => {
const version = Version.DRAFT_22;
Expand Down
4 changes: 3 additions & 1 deletion js/net/src/ietf/publisher.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2076,7 +2076,9 @@ export class Publisher {
* @internal
*/
runTrackStatusRequest(msg: TrackStatusRequest, stream: Stream): Promise<void> {
const request = new RequestStream(stream, this.#session, this.#quic);
// Nothing can follow a TRACK_STATUS, so a FIN only ends the requester's input; a reset or
// STOP_SENDING withdraws it.
const request = new RequestStream(stream, this.#session, this.#quic, { finCancels: false });
return request.serve(this.#runTrackStatusRequest(msg, request));
}

Expand Down
26 changes: 19 additions & 7 deletions js/net/src/ietf/request_stream.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,14 @@ import type { Session } from "./session.ts";
import { MalformedAuthToken } from "./token.ts";
import { type IetfVersion, Version } from "./version.ts";

/** Whether the draft treats the requester finishing its messages as cancellation. */
/**
* Whether the requester finishing its messages withdraws a request on `version`.
*
* Draft 18 asks for a reset or STOP_SENDING (section 3.3.2) and names a FIN as a cancel only for
* SUBSCRIBE_NAMESPACE and SUBSCRIBE_TRACKS (section 6.1), but our own draft-18 requesters cancel
* by FIN, so we read one that way. TRACK_STATUS passes `false` instead: nothing can follow it, so
* a requester may FIN right after it (moxygen does).
*/
function finCancels(version: IetfVersion): boolean {
return version === Version.DRAFT_18;
}
Expand Down Expand Up @@ -147,6 +154,8 @@ export class RequestStream {
readonly #stream: Stream;
readonly #session: Session;
readonly #quic?: WebTransport;
// Whether the peer's FIN withdraws the request, rather than only ending its input.
readonly #finCancels: boolean;
// The next message, read ahead of whoever takes it. Unset until someone first waits.
#ahead?: Promise<Framed | undefined>;
#taking = false;
Expand All @@ -155,12 +164,16 @@ export class RequestStream {
readonly #ended: Promise<void>;
#end!: () => void;

/** Own `stream` for a request on `session`, closing `quic` over the peer's violations. */
constructor(stream: Stream, session: Session, quic?: WebTransport) {
/**
* Own `stream` for a request on `session`, closing `quic` over the peer's violations. The
* peer's FIN withdraws the request where `finCancels`, by default as the draft has it.
*/
constructor(stream: Stream, session: Session, quic?: WebTransport, options: { finCancels?: boolean } = {}) {
this.#stream = stream;
this.writer = stream.writer;
this.#session = session;
this.#quic = quic;
this.#finCancels = options.finCancels ?? finCancels(session.version);
this.#ended = new Promise((resolve) => {
this.#end = resolve;
});
Expand Down Expand Up @@ -208,7 +221,7 @@ export class RequestStream {
*/
cancel(): void {
if (this.#closed) return;
if (finCancels(this.#session.version)) this.writer.close();
if (this.#finCancels) this.writer.close();
else this.writer.reset(new StreamError(StreamCode.Cancel, { message: "cancel" }));
}

Expand Down Expand Up @@ -256,12 +269,11 @@ export class RequestStream {
// Start reading on the first wait.
#read(): Promise<Framed | undefined> {
if (this.#ahead === undefined) {
const version = this.#session.version;
this.#ahead = this.#readAhead();
// The read ahead stops at an untaken message, so watch for the peer's end apart from it.
this.#stream.reader.closed.then(
() => {
if (finCancels(version)) this.#end();
if (this.#finCancels) this.#end();
},
() => this.#end(),
);
Expand All @@ -279,7 +291,7 @@ export class RequestStream {
const read = this.#readFramed();
read.then(
(framed) => {
if (framed === undefined && finCancels(this.#session.version)) this.#end();
if (framed === undefined && this.#finCancels) this.#end();
},
(err: unknown) => {
if (err instanceof ProtocolViolation) this.abort(err);
Expand Down
1 change: 0 additions & 1 deletion quest/m1/interop-coverage/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,6 @@ coverage on `main` at `3ab6cbf81d`.

## Required

- [Draft-18 TRACK_STATUS FIN](/quest/m1/interop-coverage/draft18-status-fin.md) - a draft-18 TRACK_STATUS followed at once by a FIN is answered, so moqx-forwarded status requests reach moq-dev publishers
- [JS subscribers FETCH](/quest/m1/interop-coverage/js-ietf-fetch.md) - `@moq/net` fetches past groups over moq-transport, and joins the CLI FETCH round

## Related
Expand Down
33 changes: 0 additions & 33 deletions quest/m1/interop-coverage/draft18-status-fin.md

This file was deleted.

Loading