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
20 changes: 11 additions & 9 deletions .agents/plans/moq-transport-20-migration.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Temporary implementation notes — delete before merge per `AGENTS.md`.
**Issue #45 verification (2026-09-16, moq-relay 0.14.17):** the shared codec
uses bare Locations in both directions. Fixed-byte tests pin SUBSCRIBE_OK,
REQUEST_OK, multi-byte IDs, following parameters/properties, and truncation.
INCLUDE_PROPERTIES keeps its length prefix.
INCLUDE_PROPERTIES keeps its length prefix (until 0.17.0; see #58).
Comment thread
mmcc marked this conversation as resolved.
Resolved

A local `moqdev/moq-relay:0.14.17` container and Playwright Chromium exercised
the publisher and subscriber worktrees together over WebTransport (`moqt-20`).
Expand Down Expand Up @@ -166,10 +166,11 @@ publisher,subscriber}.rs` and `js/net/src/ietf/{filter,parameters}.ts` on
on draft-17 and newer**, matching §10.2. Draft-14 through -16 keep the
length prefix. Older relays used a length prefix on all drafts; our
draft-20-only codec now uses the bare form for both encoding and decoding.
- **`INCLUDE_PROPERTIES` (0x35) is framed length-prefixed with a single byte
inside**, again by parity, although §10.2.21 calls it a uint8. The relay
obeys it as a publisher and sends it only to opt out (which its upstream
subscriber does not do today).
- **`INCLUDE_PROPERTIES` (0x35) was framed length-prefixed with a single byte
inside through 0.15.8**, again by parity, although §10.2.21 calls it a uint8.
moq-relay 0.17.0 (moq-dev/moq#4610) reads it as a bare byte, and so does our
codec since #58. The relay obeys it as a publisher and sends it only to opt
out (which its upstream subscriber does not do today).
- Range filters 0x26/0x28 are length-prefixed (matches the spec's explicit
Length field and our codec).
- Draft-20 PUBLISH_OK (REQUEST_OK) carries no parameters.
Expand Down Expand Up @@ -203,8 +204,8 @@ publisher,subscriber}.rs` and `js/net/src/ietf/{filter,parameters}.ts` on
behind the edge.
4. **`LARGEST_OBJECT` must encode and decode as two bare varints for
0.14.17.** Both SUBSCRIBE_OK and REQUEST_OK can carry it once content
exists. Keep INCLUDE_PROPERTIES length-prefixed; its framing did not
change.
exists. INCLUDE_PROPERTIES stayed length-prefixed until moq-relay 0.17.0
made it a bare byte (#58).
5. **Fills are not needed** for playback against the relay. Decode
`FILL_PARAMETERS` and `INCLUDE_PROPERTIES` so a peer sending them does not
kill a session (the publisher branch receives SUBSCRIBE), but requesting
Expand All @@ -226,7 +227,8 @@ publisher,subscriber}.rs` and `js/net/src/ietf/{filter,parameters}.ts` on
**0.14.17 compatibility cutover (#45, 2026-09-16):** ship the bare-location
codec together with the relay upgrade. There is no safe wire auto-detection:
old clients fail against 0.14.17 and new clients cannot use older relays'
length-prefixed locations. INCLUDE_PROPERTIES remains unchanged.
length-prefixed locations. INCLUDE_PROPERTIES remained unchanged then; #58
later made it a bare byte for 0.17.0.

The whole fleet speaks `moqt-20`, so a hard cutover is viable and is the
smaller change. Offering `['moqt-20', 'moqt-19']` and reading the negotiated
Expand Down Expand Up @@ -313,7 +315,7 @@ Branch points on a `draft: 19 | 20` value in `createMoqtSession` config:
on draft-20, matching moq-relay 0.14.17 and PR #3561.
- `MessageParameters`: add `fillParameters?: MessageParameters` (nested
`encodeMessageParameters`; decoder enforces the allow-list and rejects it on
draft-19) and `includeProperties?: 0 | 1` (length-prefixed single byte;
draft-19) and `includeProperties?: 0 | 1` (bare uint8 since #58;
reject values other than 0/1; reject on draft-19).
- `FetchRequest` on 20 collapses to `{ requestId, trackNamespace, trackName,
parameters }` with the range in `parameters.locationFilter`; the 19 shapes
Expand Down
16 changes: 6 additions & 10 deletions packages/spf/src/network/moqt/control-messages.ts
Original file line number Diff line number Diff line change
Expand Up @@ -583,7 +583,7 @@ function collectParameterEntries(parameters: MessageParameters): ParameterEntry[
}

if (parameters.includeProperties !== undefined) {
push(PARAMETER_TYPE.INCLUDE_PROPERTIES, (w) => w.writeLengthPrefixed(Uint8Array.of(parameters.includeProperties!)));
push(PARAMETER_TYPE.INCLUDE_PROPERTIES, (w) => w.writeUint8(parameters.includeProperties!));
}

return entries;
Expand Down Expand Up @@ -711,16 +711,12 @@ export function decodeMessageParameters(reader: ByteReader, scope: ParameterScop
parameters.trackNamespacePrefix = readTrackNamespace(reader);
break;
case PARAMETER_TYPE.INCLUDE_PROPERTIES: {
// §10.2.21 calls the value a uint8; moq-relay frames it
// length-prefixed by the odd-type parity rule (moq-dev/moq#3255),
// including in 0.14.17; the bare Location change does not apply here.
const value = reader.readBytes(reader.readVarint());
// moq-relay framed this length-prefixed by type parity until 0.17.0
// (moq-dev/moq#4610), which reads the §10.2.21 uint8 bare.
const include = reader.readUint8();
if (include !== 0 && include !== 1) throw new MoqtProtocolError(`invalid INCLUDE_PROPERTIES value ${include}`);

if (value.length !== 1 || value[0]! > 1) {
throw new MoqtProtocolError(`invalid INCLUDE_PROPERTIES value ${Array.from(value).join(',')}`);
}

parameters.includeProperties = value[0] as 0 | 1;
parameters.includeProperties = include;
break;
}
default: {
Expand Down
20 changes: 11 additions & 9 deletions packages/spf/src/network/moqt/tests/control-messages.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -389,22 +389,24 @@ describe('encodeMessageParameters', () => {

it('keeps parameters following a small LARGEST_OBJECT aligned', () => {
const parameters: MessageParameters = { largestObject: { group: 0, object: 1 }, forward: 1, includeProperties: 0 };
const wire = Uint8Array.of(0x03, 0x09, 0x00, 0x01, 0x07, 0x01, 0x25, 0x01, 0x00);
const wire = Uint8Array.of(0x03, 0x09, 0x00, 0x01, 0x07, 0x01, 0x25, 0x00);

expect(encodeParameters(parameters)).toEqual(wire);
expect(decodeMessageParameters(new ByteReader(wire))).toEqual(parameters);
});

it('frames INCLUDE_PROPERTIES as a length-prefixed byte and rejects values other than 0 and 1', () => {
expect(Array.from(encodeParameters({ includeProperties: 1 }))).toEqual([0x01, 0x35, 0x01, 0x01]);
// Wire vector matches moq-relay 0.17.0, which decodes 0x35 as a bare bool (moq-dev/moq#4610).
it.each([0, 1] as const)('frames INCLUDE_PROPERTIES %i as a bare byte', (includeProperties) => {
const wire = Uint8Array.of(0x01, 0x35, includeProperties);

const writer = new ByteWriter();
expect(encodeParameters({ includeProperties })).toEqual(wire);
expect(decodeMessageParameters(new ByteReader(wire))).toEqual({ includeProperties });
});

writer.writeVarint(1);
writer.writeVarint(PARAMETER_TYPE.INCLUDE_PROPERTIES);
writer.writeVarint(1);
writer.writeUint8(2);
expect(() => decodeMessageParameters(new ByteReader(writer.toBytes()))).toThrow(/INCLUDE_PROPERTIES/);
it('rejects INCLUDE_PROPERTIES values other than 0 and 1', () => {
expect(() => decodeMessageParameters(new ByteReader(Uint8Array.of(0x01, 0x35, 0x02)))).toThrow(
/INCLUDE_PROPERTIES/
);
});

it('encodes FILL_PARAMETERS as a nested parameter list', () => {
Expand Down
Loading