Skip to content
Merged
26 changes: 22 additions & 4 deletions doc/concept/standard.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,8 @@ subset drops. What a peer actually observes against this implementation:
- **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 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`.
- **Timing.** A track whose `SUBSCRIBE_OK` declares no `TIMESCALE` is untimed, as is every track on drafts 14 through 16. A Rust reader that never subscribed takes the units from `TRACK_STATUS` on draft 18 and later.
- **Strict SETUP and parameters.** Repeated unknown `SETUP` options, GREASE included, are accepted if well-formed; a repeated known option is rejected. On draft 17 and later, a `GROUP_ORDER` other than Ascending (1) or Descending (2) closes the session. Message parameters follow the negotiated draft's lists: drafts 14 and 15 ignore an unknown or misplaced parameter, draft 16 ignores one defined only for another message but closes the session on an unknown one, and draft 17 and later close it on both.
- **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, a token on a `SUBSCRIBE` or `PUBLISH_NAMESPACE` is verified like an in-band session token and authorizes that one request alone, 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 renews the token, except on a drafts 14 and 15 `PUBLISH_NAMESPACE`, which has no update, and a refused renewal ends only that request. A token on any other request is decoded and grants nothing, and a request repeating one is refused with `MALFORMED_AUTH_TOKEN`. `SUBSCRIBE_TRACKS` is refused unread, so its token is not decoded. On draft 17 and later, the negotiated [MoQ Auth extension](/concept/moq-lite#authorization) accepts additional session tokens in band.
- **Refused, not fatal.** A legal request this stack does not serve is rejected on its own and the session stays up: `FORWARD=0`, range filters, `SUBSCRIBE_TRACKS`, and the fetch forms above. On draft 19 and later, and in Rust on drafts 14 through 16, a subscription update may change only priority or renew a request token; any other update ends that subscription.
- **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, a token on a `SUBSCRIBE` or `PUBLISH_NAMESPACE` is verified like an in-band session token and authorizes that one request alone, 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 renews the token, except on a drafts 14 and 15 `PUBLISH_NAMESPACE`, which has no update, and a refused renewal ends only that request. A token on any other request is decoded and grants nothing, and a request repeating one is refused with `MALFORMED_AUTH_TOKEN`. `SUBSCRIBE_TRACKS` reads its namespace before refusal; its token is not decoded. On draft 17 and later, the negotiated [MoQ Auth extension](/concept/moq-lite#authorization) accepts additional session tokens in band.
- **Refused, not fatal.** A legal request this stack does not serve is rejected on its own and the session stays up: `FORWARD=0`, `SUBSCRIBE_TRACKS`, and the fetch forms above get `NOT_SUPPORTED`. Range Filters get `INVALID_FILTER` on draft 19 and later because the advertised filter limit is zero. On draft 21 and later, 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 and delivery timeouts; Rust also renews request tokens. 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`. On draft 18 and later a namespace update may change its prefix; suffixes after the acknowledgement are relative to that new prefix.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Move wire refusal accounting out of the concept guide

This new paragraph records exact error names and draft-by-draft behavior for several edge cases, but the scoped documentation rules reserve error codes and per-version accounting for API documentation and drafts, and say fixes or edge cases do not justify changing doc/ unless they alter what a reader would do. Keep only genuinely actionable user behavior here and move or link the refusal matrix to the adjacent reference material.

AGENTS.md reference: doc/AGENTS.md:L4-L6

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Keeping this as is. The quest's plan, settled with the maintainer, places these answers in doc/concept/standard.md: update the existing "Refused, not fatal" bullet and give each deliberate deviation a line, so the next conformance validator run has a reason to point at. This page is the existing per-draft conformance summary for moq-transport peers, and the change edits the bullet that already covers refusals instead of adding a new section. Moving the conformance list off this page would be a separate doc restructuring.

(Written by Opus 5.5)

- **Objects and datagrams.** Rust relays preserve Object IDs, gaps, object properties, FIRST\_OBJECT, and END\_OF\_GROUP status objects between moq-transport peers for subgroup 0. Datagrams retain their IDs, properties, priority, and status. Plain Rust readers and moq-lite peers see consecutive frames and normal datagram payloads; JavaScript supports only normal datagrams at Object ID 0. A malformed datagram closes the session; a relayed one the downstream draft cannot carry is dropped. A relayed Timestamp leaves in the units the downstream response declares, and is dropped where it declares none (drafts 14 through 16), as for a plain frame; an immutable one that would change or vanish is refused. Property 0x06 is a draft-ietf-moq-loc-03 Timestamp only before draft 19, which reassigns it to SUBGROUP\_DELIVERY\_TIMEOUT, so it is dropped across that boundary, or refused when immutable. From draft 15, a status object carrying properties is refused, and one relayed from draft 14 leaves without them. A `FETCH` carries the END\_OF\_GROUP object on drafts 14 and 15; later drafts have no FETCH status, so their 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.
- **Priority.** Higher is served first. The IETF default of 128 is this stack's 127, and a track that never sets one is 127.
- **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 All @@ -52,15 +52,16 @@ See [Encryption](/concept/hang#encryption).

### Deliberate deviations

These four answers differ from the draft on purpose. They are the
product's model, not bugs, and the relay does not change them.
These answers deliberately differ from the draft or exercise its implementation
choices. They follow the product model.

- **One publisher per path.** A broadcast path names one piece of content, so a
`SUBSCRIBE` goes to one route, not to every publisher whose namespace matches.
[Draft 16 §8.5](https://www.ietf.org/archive/id/draft-ietf-moq-transport-16.html#section-8.5)
requires the relay to send that `SUBSCRIBE` to all matching publishers. See
[publisher epochs](/concept/moq-lite#publisher-epochs) for how that one route
is chosen.

- **Plain readers leave object properties out.**
[Draft 18 §2.5](https://www.ietf.org/archive/id/draft-ietf-moq-transport-18.html#section-2.5)
says a relay that does not understand a property still forwards and caches
Expand All @@ -69,6 +70,7 @@ product's model, not bugs, and the relay does not change them.
Immutable property blocks retain their bytes. Forwarding is refused when the
negotiated drafts use incompatible key or integer encodings, or when the block
holds a Timestamp in units the response does not declare.

- **`SUBSCRIBE_OK` before an old source answers.** moq-lite 01 through 04 have
no track stream, so the relay cannot learn from that source whether the track
exists before answering. A moq-transport subscriber gets `SUBSCRIBE_OK`
Expand All @@ -78,12 +80,28 @@ product's model, not bugs, and the relay does not change them.
requires an established upstream subscription before `SUBSCRIBE_OK`. From
moq-lite 05 the track stream answers first, and a missing track is refused
before `SUBSCRIBE_OK`.

- **An unknown token alias closes the session.** No alias is ever registered,
so a `DELETE` or `USE_ALIAS` token on a request names one that does not exist.
[Draft 21 §8.9](https://www.ietf.org/archive/id/draft-ietf-moq-transport-21.html#section-8.9)
rejects the message, but `UNKNOWN_AUTH_TOKEN_ALIAS` exists only as a session
termination code, so we close the session with it.

- **Deduplicated subscriptions and discovery.** Shared subscriptions and overlapping
namespace prefixes are coalesced internally, so `DUPLICATE_SUBSCRIPTION` and
`PREFIX_OVERLAP` are never sent.

- **Delivery timeouts are advisory.** `OBJECT_DELIVERY_TIMEOUT` and
`SUBGROUP_DELIVERY_TIMEOUT` are accepted on subscriptions and their updates,
but do not drop objects or reset subgroups. Latency enforcement uses
presentation time instead of wall-clock delivery deadlines.

- **Rendezvous waits are capped at zero.** A `SUBSCRIBE` with a positive
`RENDEZVOUS_TIMEOUT` gets `TIMEOUT` immediately if no publisher exists;
absent or zero still gets `DOES_NOT_EXIST`.
[Draft 21 §9.20.7](https://www.ietf.org/archive/id/draft-ietf-moq-transport-21.html#section-9.20.7)
permits the publisher to cap the wait.

## MSF

The MoQ Streaming Format is a catalog, playing the role HLS playlists and SDP
Expand Down
91 changes: 91 additions & 0 deletions js/net/bench/requests.ts
Original file line number Diff line number Diff line change
@@ -1,8 +1,19 @@
/** Sweep request restart and cancellation over independent origin and waiter dimensions. */
import { Producer as Broadcast } from "../src/broadcast";
import * as Epoch from "../src/epoch";
import { NativeSession } from "../src/ietf/adapter";
import { Publisher as IetfPublisher } from "../src/ietf/publisher";
import { RequestOk } from "../src/ietf/request";
import {
SubscribeNamespace,
SubscribeNamespaceEntry,
SubscribeNamespaceEntryDone,
} from "../src/ietf/subscribe_namespace";
import { ALPN, Version } from "../src/ietf/version";
import { createMockTransportPair } from "../src/mock";
import { Producer } from "../src/origin";
import * as Path from "../src/path";
import { Stream } from "../src/stream";
import { wireOf } from "../src/wire";

const settle = () => new Promise<void>((resolve) => setImmediate(resolve));
Expand Down Expand Up @@ -248,3 +259,83 @@ for (const survivor of [false, true])
settled.sort((a, b) => a - b);
console.log(`${survivor},${routes},${cancelled},${active[3].toFixed(2)},${settled[3].toFixed(2)}`);
}

// Prefix updates withdraw the old set and replay the new set. Sweep both the
// namespaces per prefix and the concurrent requesting peers, including wire encoding.
console.log("namespace_update,draft,namespaces,subscribers,update_us");
for (const [version, alpn] of [
[Version.DRAFT_18, ALPN.DRAFT_18],
[Version.DRAFT_21, ALPN.DRAFT_21],
] as const)
for (const namespaces of [1, 32, 128])
for (const subscribers of [1, 8]) {
const origin = new Producer();
const sources = [];
for (const prefix of ["a", "b"])
for (let i = 0; i < namespaces; i++) {
const source = origin.createBroadcast(Path.from(`${prefix}/${i}`));
source.announce();
sources.push(source);
}
const peers = await Promise.all(
Array.from({ length: subscribers }, async () => {
const pair = createMockTransportPair(alpn);
const pub = new IetfPublisher({
quic: pair.server,
session: new NativeSession(pair.server, version, false),
publish: origin.consume(),
requiresSolicitation: true,
});
const client = await Stream.open(pair.client, { version });
const server = await Stream.accept(pair.server, version);
if (!server) throw new Error("missing namespace stream");
const running = pub.runSubscribeNamespace(
new SubscribeNamespace({ requestId: 0n, namespace: Path.from("a") }),
server,
);
if ((await client.reader.u53()) !== RequestOk.id) throw new Error("missing initial OK");
await RequestOk.decode(client.reader, version);
for (let i = 0; i < namespaces; i++) {
if ((await client.reader.u53()) !== SubscribeNamespaceEntry.id)
throw new Error("missing initial namespace");
await SubscribeNamespaceEntry.decode(client.reader, version);
}
return { client, running };
}),
);
const samples: number[] = [];
try {
for (let round = 0; round < 7; round++) {
const start = performance.now();
await Promise.all(
peers.map(async ({ client }) => {
await client.writer.write(
Uint8Array.from([0x02, 0, 6, (round + 1) * 2, 1, 0x34, 1, 1, round % 2 ? 97 : 98]),
);
for (let i = 0; i < namespaces; i++) {
if ((await client.reader.u53()) !== SubscribeNamespaceEntryDone.id)
throw new Error("missing old withdrawal");
await SubscribeNamespaceEntryDone.decode(client.reader, version);
}
if ((await client.reader.u53()) !== RequestOk.id) throw new Error("missing update OK");
await RequestOk.decode(client.reader, version);
for (let i = 0; i < namespaces; i++) {
if ((await client.reader.u53()) !== SubscribeNamespaceEntry.id)
throw new Error("missing replay namespace");
await SubscribeNamespaceEntry.decode(client.reader, version);
}
}),
);
if (round > 1) samples.push((performance.now() - start) * 1000);
}
samples.sort((a, b) => a - b);
console.log(
`namespace_update,${version === Version.DRAFT_18 ? 18 : 21},${namespaces},${subscribers},${samples[2].toFixed(2)}`,
);
} finally {
for (const peer of peers) peer.client.close();
await Promise.all(peers.map((peer) => peer.running));
for (const source of sources) source.close();
origin.close();
}
}
12 changes: 7 additions & 5 deletions js/net/src/ietf/connection.ts
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ import { type RequestKind, toRequestCode } from "./error.ts";
import { Fetch, FetchError, FetchHeader } from "./fetch.ts";
import { GoAway } from "./goaway.ts";
import * as Message from "./message.ts";
import * as Namespace from "./namespace.ts";
import { Group } from "./object.ts";
import { Publish, PublishError } from "./publish.ts";
import { PublishNamespace, PublishNamespaceError } from "./publish_namespace.ts";
Expand Down Expand Up @@ -401,13 +402,14 @@ export class Connection implements Established {
if (this.#session.version < Version.DRAFT_18) {
throw new ProtocolViolation("SUBSCRIBE_TRACKS before draft-18");
}
const requestId = await Message.decode(stream.reader, async (reader) => {
const id = await reader.u62();
const request = await Message.decode(stream.reader, async (reader) => {
const requestId = await reader.u62();
const namespace = await Namespace.decode(reader);
await reader.readAll();
return id;
return { requestId, namespace };
});
this.#session.spendRequest(requestId);
await this.#publisher.runSubscribeTracks(stream);
this.#session.spendRequest(request.requestId);
await this.#publisher.runSubscribeTracks(stream, request.namespace);
break;
}
case BigInt(TrackStatusRequest.id): {
Expand Down
10 changes: 10 additions & 0 deletions js/net/src/ietf/error.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ const CONDITIONS: RequestCondition[] = [
"not_supported",
"does_not_exist",
"invalid_range",
"invalid_filter",
"invalid_joining_request_id",
"uninterested",
"malformed_track",
Expand Down Expand Up @@ -214,3 +215,12 @@ test("stream reset codes are shared only where the draft agrees", () => {
expect(sharedStreamCode(StreamCode.MalformedTrack, Version.DRAFT_15)).toBe(false);
expect(sharedStreamCode(StreamCode.MalformedTrack, Version.DRAFT_16)).toBe(true);
});

test("INVALID_FILTER is registered from draft 19", () => {
for (const version of ALL) {
expect(toRequestCode("invalid_filter", "subscribe", version)).toBe(version >= Version.DRAFT_19 ? 0x36 : 0);
expect(fromRequestCode(0x36, "fetch", version)).toBe(
version >= Version.DRAFT_19 ? "invalid_filter" : undefined,
);
}
});
4 changes: 4 additions & 0 deletions js/net/src/ietf/error.ts
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,7 @@ export type RequestCondition =
| "not_supported"
/** The broadcast or track the peer asked for is not here. */
| "invalid_range"
| "invalid_filter"
| "invalid_joining_request_id"
| "does_not_exist"
/** The content the peer offered is not wanted here, so it should stop offering it. */
Expand Down Expand Up @@ -188,6 +189,8 @@ function goingAway(version: IetfVersion): number | undefined {
*/
export function toRequestCode(condition: RequestCondition, kind: RequestKind, version: IetfVersion): number {
switch (condition) {
case "invalid_filter":
return version >= Version.DRAFT_19 ? 0x36 : INTERNAL_ERROR;
case "internal":
return INTERNAL_ERROR;
case "unauthorized":
Expand Down Expand Up @@ -236,6 +239,7 @@ export function fromRequestCode(code: number, kind: RequestKind, version: IetfVe
return "not_supported";
}

if (code === 0x36 && version >= Version.DRAFT_19) return "invalid_filter";
if (code === doesNotExist(kind, version)) return "does_not_exist";
if (code === invalidRange(kind, version)) return "invalid_range";
if (code === invalidJoiningRequestId(kind, version)) return "invalid_joining_request_id";
Expand Down
Loading
Loading