Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
5e0b768
claim quest/m0/ietf-params-per-draft
kixelated Oct 7, 2026
f2977fc
fix(net): accept each draft's message parameters
kixelated Oct 7, 2026
0f47881
Merge remote-tracking branch 'origin/main' into quest/m0/ietf-params-…
kixelated Oct 7, 2026
3718bef
fix(js): decode a negotiated PUBLISH_NAMESPACE against its own parame…
kixelated Oct 8, 2026
7394fa8
Merge remote-tracking branch 'origin/main' into quest/m0/ietf-params-…
kixelated Oct 8, 2026
e17afa8
Merge remote-tracking branch 'origin/main' into quest/m0/ietf-params-…
kixelated Oct 8, 2026
234944f
chore: finish the params-per-draft and first-object-zero quests
kixelated Oct 8, 2026
44dfef1
Merge remote-tracking branch 'origin/main' into quest/m0/ietf-params-…
kixelated Oct 8, 2026
05df719
Merge remote-tracking branch 'origin/main' into quest/m0/ietf-params-…
kixelated Oct 8, 2026
10accc3
fix(net): reject TRACK_NAMESPACE_PREFIX on a subscription update
kixelated Oct 8, 2026
4ef29ce
Merge remote-tracking branch 'origin/main' into merge-5028
kixelated Oct 8, 2026
698224f
style(net): format Parameters.decode signature
kixelated Oct 8, 2026
2bbec51
Merge remote-tracking branch 'origin/main' into merge-5028
kixelated Oct 8, 2026
7d84b79
Merge remote-tracking branch 'origin/main' into merge-5028
kixelated Oct 8, 2026
717aa1c
Merge remote-tracking branch 'origin/main' into merge-5028
kixelated Oct 8, 2026
766e7b1
Merge remote-tracking branch 'origin/main' into merge-5028
kixelated Oct 8, 2026
7a9a034
Merge remote-tracking branch 'origin/main' into merge-5028
kixelated Oct 8, 2026
0f709fc
Merge remote-tracking branch 'origin/main' into merge-5028
kixelated Oct 8, 2026
5db990a
Merge remote-tracking branch 'origin/main' into pr-5028-land
kixelated Oct 8, 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
4 changes: 2 additions & 2 deletions doc/concept/standard.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,8 +28,8 @@ subset drops. What a peer actually observes against this implementation:
- **Pull.** Subscribers ask. Single-track `PUBLISH` offers are declined; announce a namespace and serve the resulting subscriptions. Announcements go out unsolicited, and we also ask for every prefix we may discover. 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 never send `PUBLISH`: 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.
- **History is one group.** On drafts 14 through 19 a `FETCH` returns one whole group from the cache, or the saved prefix of the group a new subscription just joined. A range of groups is refused, as is any `FETCH` on draft 20 and later. JavaScript publishing refuses every `FETCH`. Datagrams are never fetchable.
- **Timing.** A track whose `SUBSCRIBE_OK` declares no `TIMESCALE` is untimed, as is every track on drafts 14 through 16. A reader that never subscribed reads a standalone fetch untimed.
- **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.
- **One credential per session**, carried in `SETUP` and forwarded to the [auth server](/bin/relay/auth#the-contract) unverified. A token attached to an individual request is ignored. An alias reference, a second token, or a parameter the negotiated draft does not define closes the session.
- **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 credential per session**, carried in `SETUP` and forwarded to the [auth server](/bin/relay/auth#the-contract) unverified. A token attached to an individual request is ignored. An alias reference or a second token closes the session.
- **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, `TRACK_STATUS`, `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; any other update ends that subscription.
- **Datagrams** are a single normal object at object 0, forwarded without renumbering. Anything else is dropped, and a malformed one closes the session. Rust and JavaScript both carry them on every draft.
- **Priority.** Higher is served first. The IETF default of 128 is this stack's 127, and a track that never sets one is 127.
Expand Down
22 changes: 22 additions & 0 deletions js/net/src/ietf/cluster.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ import { type Hop, HopSchema, UNKNOWN_HOP } from "../hop.ts";
import * as Path from "../path.ts";
import { Reader, Writer } from "../stream.ts";
import * as Cluster from "./cluster.ts";
import * as Message from "./message.ts";
import * as Namespace from "./namespace.ts";
import { Parameters, SetupOption, SetupOptions } from "./parameters.ts";
import { PublishNamespace, PublishNamespaceUpdate } from "./publish_namespace.ts";
import { SubscribeNamespaceEntry } from "./subscribe_namespace.ts";
Expand Down Expand Up @@ -229,6 +231,26 @@ test("Cluster: PUBLISH_NAMESPACE carries the parameters only once negotiated", a
await expect(PublishNamespace.decode(reader(await encode(bare)), VERSION, true)).rejects.toThrow(ProtocolViolation);
});

test("Cluster: a negotiated PUBLISH_NAMESPACE may carry AUTHORIZATION_TOKEN", async () => {
// The advertisement shares its decode with NAMESPACE, whose list has no token. A
// PUBLISH_NAMESPACE's own list does, so the token must not close the session.
const advert = { hops: hops(7n, 9n), cost: 5n };
const withToken = {
async encode(w: Writer, version: IetfVersion) {
await Message.encode(w, async (wr) => {
await wr.u62(1n);
await Namespace.encode(wr, Path.from("alice.hang"));
const params = Cluster.intoParams(advert);
params.bytes.set(0x03n, new Uint8Array([1, 2, 3])); // AUTHORIZATION_TOKEN
await params.encode(wr, version);
});
},
};

const decoded = await PublishNamespace.decode(reader(await encode(withToken)), VERSION, true);
expect(decoded.cluster).toEqual(advert);
});

test("Cluster: every malformed PUBLISH_NAMESPACE update is a protocol violation", async () => {
const valid = await encode(new PublishNamespaceUpdate({ requestId: 1n, update: { cost: 2n } }));
const trailing = new Uint8Array(valid.byteLength + 1);
Expand Down
11 changes: 8 additions & 3 deletions js/net/src/ietf/cluster.ts
Original file line number Diff line number Diff line change
Expand Up @@ -204,18 +204,23 @@ function encodeHops(hops: Hop[]): Uint8Array {
}

/**
* Read the parameters a negotiated session puts on every advertisement.
* Read the parameters a negotiated session puts on every advertisement, checked against
* the list of the message that carries them (PUBLISH_NAMESPACE also allows a token).
*
* The parameter block is mandatory there, so a message that ends before it (the base form)
* or one whose block does not parse is the peer's violation, same as a block that parses but
* carries no HOP_PATH.
*
* @internal
*/
export async function decodeParams(r: Reader, version: IetfVersion): Promise<Advert> {
export async function decodeParams(
r: Reader,
version: IetfVersion,
message: "namespace" | "publish-namespace",
): Promise<Advert> {
let params: Parameters;
try {
params = await Parameters.decode(r, version);
params = await Parameters.decode(r, version, message);
} catch (err) {
throw new ProtocolViolation(reason(err), { cause: err });
}
Expand Down
2 changes: 1 addition & 1 deletion js/net/src/ietf/fetch.ts
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,7 @@ export class Fetch {
}
}

const params = await Parameters.decode(r, version);
const params = await Parameters.decode(r, version, "fetch");
if (params.rangeFilters && !hasRangeFilters(version)) {
throw new Error("Range Filters need draft-19");
}
Expand Down
68 changes: 68 additions & 0 deletions js/net/src/ietf/ietf.test.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
import { expect, test } from "bun:test";
import { ProtocolViolation } from "../error.ts";
import * as Path from "../path.ts";
import { type Cursor, Reader, Writer } from "../stream.ts";
import { Timescale, Timestamp } from "../time.ts";
Expand Down Expand Up @@ -1559,6 +1560,73 @@ test("SubscribeNamespace: draft-18 omits subscribe options", async () => {
}
});

// FORWARD is legal on SUBSCRIBE_NAMESPACE through draft-17. A value other than 0 or 1
// still closes the session. Draft-18 dropped it from this message.
test("SubscribeNamespace: FORWARD follows the draft", async () => {
const legacy = (version: IetfVersion, value: number) => {
const body = [0x01];
if (version === Version.DRAFT_17) body.push(0x00);
body.push(0x00, 0x01, 0x01, 0x10, value);
return framed(body);
};

for (const version of [Version.DRAFT_16, Version.DRAFT_17] as const) {
const decoded = await decodeVersioned(
legacy(version, 0),
SubscribeNamespace.SubscribeNamespaceLegacy.decode,
version,
);
expect(decoded.requestId).toBe(1n);
await expect(
decodeVersioned(legacy(version, 2), SubscribeNamespace.SubscribeNamespaceLegacy.decode, version),
).rejects.toThrow(ProtocolViolation);
}

await expect(
decodeVersioned(
framed([0x01, 0x00, 0x01, 0x10, 0x00]),
SubscribeNamespace.SubscribeNamespace.decode,
Version.DRAFT_18,
),
).rejects.toThrow(ProtocolViolation);
});

// EXPIRES is a draft-16 message parameter, but not on SUBSCRIBE. Draft-16 ignores it and
// still reads the parameter after it. Draft-18 closes the session.
test("Parameters: a known parameter on the wrong message", async () => {
const block = new Uint8Array([0x02, 0x08, 0x05, 0x18, 0x07]);
const ignored = await Parameters.decode(
new Reader(undefined, block, Version.DRAFT_16),
Version.DRAFT_16,
"subscribe",
);
expect(ignored.subscriberPriority).toBe(7);
expect(ignored.expires).toBeUndefined();

await expect(
Parameters.decode(new Reader(undefined, block, Version.DRAFT_18), Version.DRAFT_18, "subscribe"),
).rejects.toThrow(ProtocolViolation);
});

// TRACK_NAMESPACE_PREFIX updates a SUBSCRIBE_NAMESPACE or SUBSCRIBE_TRACKS only, so a
// subscription's REQUEST_UPDATE carrying it closes the session instead of being acked.
test("Parameters: TRACK_NAMESPACE_PREFIX is not a subscription update parameter", async () => {
// One parameter: TRACK_NAMESPACE_PREFIX (0x34), a one-field namespace "a".
const block = new Uint8Array([0x01, 0x34, 0x01, 0x01, 0x61]);
await expect(
Parameters.decode(new Reader(undefined, block, Version.DRAFT_18), Version.DRAFT_18, "request-update"),
).rejects.toThrow(ProtocolViolation);
});

test("Subscribe: SUBGROUP_DELIVERY_TIMEOUT follows its draft", async () => {
const body = framed([...TRACK_HEAD, 0x01, 0x06, 0x00]);
await expect(decodeVersioned(body, Subscribe.Subscribe.decode, Version.DRAFT_16)).rejects.toThrow(
ProtocolViolation,
);
const decoded = await decodeVersioned(body, Subscribe.Subscribe.decode, Version.DRAFT_18);
expect(decoded.trackName).toBe("video");
});

test("Group: draft-18 sets FIRST_OBJECT bit, draft-17 does not", async () => {
const makeGroup = () =>
new Group({
Expand Down
158 changes: 155 additions & 3 deletions js/net/src/ietf/parameters.ts
Original file line number Diff line number Diff line change
Expand Up @@ -226,6 +226,126 @@ const MSG_PARAM_SUBSCRIPTION_FILTER = 0x21n;
const MSG_PARAM_FILL_PARAMETERS = 0x23n;
/// HOP_PATH, from the MoQ Cluster extension. See `cluster.ts`.
const MSG_PARAM_HOP_PATH = 0x40b57n;
/// ACTIVE_COUNT, from the MoQ Active Count extension.
const MSG_PARAM_ACTIVE_COUNT = 0x40b66n;

/// Message parameter ids defined in draft-16. A known id on the wrong message is ignored.
const DRAFT16_MESSAGE_PARAMS: readonly bigint[] = [0x02n, 0x03n, 0x08n, 0x09n, 0x10n, 0x20n, 0x21n, 0x22n, 0x32n];

/** Which control message the parameter block belongs to. Omitted keeps the unfiltered decode. */
type ControlMessage =
| "subscribe"
| "subscribe-ok"
| "subscribe-update"
| "subscribe-namespace"
| "publish"
| "publish-namespace"
| "fetch"
| "request-ok"
| "request-update"
| "namespace";

function draft20(version: IetfVersion): boolean {
return version >= Version.DRAFT_20;
}

/** True when this draft's definition of `message` includes `id`. */
function allows(message: ControlMessage, version: IetfVersion, id: bigint): boolean {
const d15 = version === Version.DRAFT_15;
const d16 = version === Version.DRAFT_16;
const d17 = version === Version.DRAFT_17;
const from16 = version >= Version.DRAFT_16;
const from17 = version >= Version.DRAFT_17;
const from18 = version >= Version.DRAFT_18;
const from19 = version >= Version.DRAFT_19;
const legacyForward = d15 || d16 || d17;
const auth = id === MSG_PARAM_AUTHORIZATION_TOKEN;
const forward = id === MSG_PARAM_FORWARD;
const priority = id === MSG_PARAM_SUBSCRIBER_PRIORITY;
const filter = id === MSG_PARAM_SUBSCRIPTION_FILTER;
const order = id === MSG_PARAM_GROUP_ORDER;
const expires = id === MSG_PARAM_EXPIRES;
const largest = id === MSG_PARAM_LARGEST_OBJECT;
const objectTimeout = id === MSG_PARAM_DELIVERY_TIMEOUT;
const subgroupTimeout = id === MSG_PARAM_SUBGROUP_DELIVERY_TIMEOUT && from18;
const range = id >= 0x25n && id <= 0x28n && from19;
const trackRange = id === MSG_PARAM_TRACK_PROPERTY_FILTER && from19;
const fill = id === MSG_PARAM_FILL_PARAMETERS && draft20(version);
const include = id === MSG_PARAM_INCLUDE_PROPERTIES && draft20(version);
const newGroup = id === MSG_PARAM_NEW_GROUP_REQUEST && from16;

switch (message) {
case "subscribe":
return (
objectTimeout ||
auth ||
(id === MSG_PARAM_MAX_CACHE_DURATION && from17) ||
subgroupTimeout ||
forward ||
priority ||
filter ||
order ||
fill ||
range ||
newGroup ||
include
);
case "subscribe-ok":
return (id === MSG_PARAM_MAX_CACHE_DURATION && d15) || expires || largest || (order && d15);
case "subscribe-update":
case "request-update":
return (
objectTimeout ||
auth ||
subgroupTimeout ||
forward ||
priority ||
filter ||
fill ||
range ||
trackRange ||
newGroup
);
case "subscribe-namespace":
return auth || (forward && legacyForward) || id === MSG_PARAM_HIDDEN;
case "publish":
return (
(objectTimeout && (d15 || draft20(version))) ||
auth ||
(subgroupTimeout && draft20(version)) ||
expires ||
largest ||
forward ||
(priority && draft20(version)) ||
(filter && draft20(version)) ||
(order && (d15 || draft20(version)))
);
case "publish-namespace":
return auth || id === MSG_PARAM_HOP_PATH || id === MSG_PARAM_ROUTE_COST;
case "fetch":
return (
auth ||
(id === MSG_PARAM_FILL_TIMEOUT && from18) ||
priority ||
(filter && draft20(version)) ||
order ||
range ||
include
);
case "request-ok":
return expires || largest || id === MSG_PARAM_ACTIVE_COUNT;
case "namespace":
return id === MSG_PARAM_HOP_PATH || id === MSG_PARAM_ROUTE_COST;
}
}

async function skipKvp(r: Reader, id: bigint): Promise<void> {
if (id % 2n === 0n) {
await r.u62();
} else {
await r.read(await r.u53());
}
}

/// The object Range Filters (draft-19): SUBGROUP, OBJECTID, PRIORITY and OBJECT_PROPERTY.
/// Each is length prefixed whatever the parity of its id.
Expand Down Expand Up @@ -254,6 +374,7 @@ function getMessageParamKind(id: bigint): MessageParamKind {
case MSG_PARAM_EXPIRES:
case MSG_PARAM_ROUTE_COST:
case MSG_PARAM_HIDDEN:
case MSG_PARAM_ACTIVE_COUNT:
return "varint";
case MSG_PARAM_PUBLISHER_PRIORITY:
case MSG_PARAM_SUBSCRIBER_PRIORITY:
Expand Down Expand Up @@ -574,7 +695,16 @@ export class Parameters {
}
}

static async decode(r: Reader, version: IetfVersion): Promise<Parameters> {
/**
* Decode a parameter block.
*
* `message`, when set, is the allow-list for that control message. A parameter the
* draft defines for a different message is ignored through draft-16 and closes the
* session from draft-17 on. An id the draft does not define at all closes from
* draft-16 on. Draft-14 and draft-15 ignore anything the message does not list.
* Omitting `message` keeps the previous decode, which stores every id.
*/
static async decode(r: Reader, version: IetfVersion, message?: ControlMessage): Promise<Parameters> {
const count = await r.u53();
const params = new Parameters();

Expand All @@ -591,12 +721,29 @@ export class Parameters {
prevType = id;
}

if (message !== undefined && !allows(message, version, id)) {
// Draft-17 on has no length on a parameter value, so an unlisted id cannot be skipped.
const ignore =
version === Version.DRAFT_14 ||
version === Version.DRAFT_15 ||
(version === Version.DRAFT_16 && DRAFT16_MESSAGE_PARAMS.includes(id));
if (!ignore) {
throw new ProtocolViolation(`message parameter ${id} is not defined for ${message}`);
}
await skipKvp(r, id);
continue;
}

if (version === Version.DRAFT_14 || version === Version.DRAFT_15 || version === Version.DRAFT_16) {
if (id % 2n === 0n) {
if (params.vars.has(id)) {
throw new Error(`duplicate message parameter id: ${id.toString()}`);
}
const varint = await r.u62();
// A bool is a varint here. Only 0 and 1 are legal once the message lists it.
if (message !== undefined && id === MSG_PARAM_FORWARD && varint !== 0n && varint !== 1n) {
throw new ProtocolViolation(`invalid message parameter value: ${id}`);
}
params.vars.set(id, varint);
} else {
const size = await r.u53();
Expand Down Expand Up @@ -640,9 +787,14 @@ export class Parameters {
params.vars.set(id, BigInt(value));
break;
}
case "bool":
params.vars.set(id, (await r.bool()) ? 1n : 0n);
case "bool": {
const value = await r.u8();
if (value !== 0 && value !== 1) {
throw new ProtocolViolation(`invalid message parameter value: ${id}`);
}
params.vars.set(id, BigInt(value));
break;
}
case "location": {
// Two bare varints from draft-17 on; see the matching comment in encode.
const groupId = await r.u62();
Expand Down
6 changes: 3 additions & 3 deletions js/net/src/ietf/publish.ts
Original file line number Diff line number Diff line change
Expand Up @@ -133,10 +133,10 @@ export class Publish {
});
}
// v15+: parameters followed by Track Properties (draft-17+)
const params = await Parameters.decode(r, version);
const params = await Parameters.decode(r, version, "publish");
const properties = await Properties.decode(r, version);
// GROUP_ORDER is only legal here through draft-15, but keep accepting it so a peer that
// still sends it doesn't have its session torn down over a hint.
// GROUP_ORDER is legal here in draft-15 and again from draft-20. Draft-16 ignores it.
// Draft-17 through draft-19 close the session.
const groupOrder = properties.groupOrder ?? params.groupOrder ?? 0x02;
const forward = params.forward ?? true;
const largest = params.largest;
Expand Down
6 changes: 3 additions & 3 deletions js/net/src/ietf/publish_namespace.ts
Original file line number Diff line number Diff line change
Expand Up @@ -62,11 +62,11 @@ export class PublishNamespace {
}
const trackNamespace = await Namespace.decode(r);
if (negotiated) {
const cluster = await Cluster.decodeParams(r, version);
const cluster = await Cluster.decodeParams(r, version, "publish-namespace");
return new PublishNamespace({ requestId, trackNamespace, cluster });
}

await Parameters.decode(r, version); // ignore parameters
await Parameters.decode(r, version, "publish-namespace");
return new PublishNamespace({ requestId, trackNamespace });
}
}
Expand Down Expand Up @@ -134,7 +134,7 @@ export class PublishNamespaceUpdate {
if (version === Version.DRAFT_17) {
await r.u62(); // required_request_id_delta (draft-17 only, removed in draft-18 per #1615)
}
const params = await Parameters.decode(r, version);
const params = await Parameters.decode(r, version, "publish-namespace");
return new PublishNamespaceUpdate({ requestId, update: Cluster.updateFromParams(params) });
}
}
Expand Down
Loading
Loading