Repository navigation
Description
Summary
moq-relay 0.14.17 (released 2026-09-14, moq-relay-v0.14.17) changes how the relay frames the LARGEST_OBJECT (0x09) message parameter. The spf MoQ engine on mmcc/moq (playback) and mmcc/moq-publisher (publishing) was deliberately written to the old framing, so once the relays move to 0.14.17:
- the player fails to decode
SUBSCRIBE_OKfor any track with content and closes the session, and - the publisher's own
SUBSCRIBE_OK/REQUEST_OKare misparsed by the relay once a track has content, because the publisher reportsLARGEST_OBJECTtoo.
This is the same defect as muxinc/relay-sdks#55; the two codecs share the same lineage and the same comment. The relay bump is staged as a draft in muxinc/switchboard#16 and is being held on both issues. The same flag day applies to relay.mux.dev, which the migration plan says was on 0.14.14 as of 2026-09-02.
What changed upstream
moq-dev/moq#3561 (closes moq-dev/moq#3558), first shipped in relay 0.14.17:
- On draft-17 and newer,
LARGEST_OBJECTis a bare Location, two consecutive varints(Group, Object), with no Length prefix. Draft-14 through -16 keep the length-prefixed form. SUBSCRIBE_OKcarriesLARGEST_OBJECTon every draft from 15 up whenever the track has content. On draft-20 it already did, so for this engine only the framing changes.- Only
impl Param for Locationchanged.INCLUDE_PROPERTIES(0x35) is still length-prefixed, so that part of the codec and of the migration plan stays correct.
Both the codec comment and .agents/plans/moq-transport-20-migration.md cite moq-dev/moq#3255, which flagged the framing as a spec conflict. Upstream has since resolved it the other way, to what moq-playa, red5-moq-relay and cloudflare/moq-rs already do.
On the wire
Location {group: 255, object: 128} as the only message parameter, draft-17 through draft-20 (vectors from rs/moq-net/src/ietf/parameters.rs upstream):
relay <= 0.14.15: 01 09 04 80 ff 80 80 count=1, type=0x09, len=4, group, object
relay 0.14.17: 01 09 80 ff 80 80 count=1, type=0x09, group, object
Feeding the new bytes to the current codec reads 80 ff (255) as the Length and runs out of buffer. With a small group id it swallows the object varint plus whatever follows and fails on trailing bytes or the next parameter. Either way: MoqtProtocolError.
Where it breaks
Playback (mmcc/moq @ bd3b6f2a1)
- Negotiates
moqt-20. writeLocationParameter/readLocationParameterframe the value with a length, per the comment above them; theLARGEST_OBJECTdecode case uses them.- A decode error on the request stream ends in
Session.#fatal, which closes the transport with the protocol error code. The playback side never readslargestObject, so nothing downstream of the codec is involved.
Publishing (mmcc/moq-publisher @ c44e5b3cf, includes the PR #42 moqt-20 cutover)
- Same codec (helpers, decode case).
- Unlike the relay-sdks publishers, this one sends
LARGEST_OBJECT: inSUBSCRIBE_OKand in theREQUEST_OKforREQUEST_UPDATE, whenevergetLargestObject()has a value. A 0.14.17 relay decodes that length-prefixed value as bare varints and misparses the rest of the message, so the relay's pull from a v10 publisher fails as soon as the track has content and the relay re-subscribes or updates. - Once the framing is fixed, a second change lands on the publisher for the first time. From 0.14.17 the relay's draft-20 pull is a Next Object filter plus
FILL_PARAMETERSwithStartGroup=1(moq-dev/moq#3325), replacing therelative-group 1pull the test hub encodes.#fillRequestedand the fill fetch stream it triggers are implemented, but the comment there says "The known relays never send FILL_PARAMETERS today", so this path has only ever run against the in-process hub. With aLARGEST_OBJECTadvertised, the relay expects that fill stream; a publisher that advertises but never serves leaves the joined group unfinished until the subscription ends.
Tests
The publish relay-hub.ts mirrors relay 0.14.14 and encodes LARGEST_OBJECT through the same codec, so the suites cannot see this.
Proposed fix
- On draft-17 and newer, write and read
LARGEST_OBJECTas two bare varints. The engine only speaks draft-20, so the two helpers can simply be replaced;mmcc/moq-resiliencestill shows the barewriteLocation/readLocationform this codec used before the moqt-20 cutover. - Update the codec comment and the "What moq-relay does" section of the migration plan, and re-pin the byte vectors in the codec tests.
- Update
relay-hub.tsto send the 0.14.17 pull (Next Object +FILL_PARAMETERS StartGroup=1) so the fill-serving path is exercised in CI. - Run a live pass against
moqdev/moq-relay:0.14.17covering playback of a track with content, and publishing where the relay re-subscribes after content exists, soLARGEST_OBJECTis actually on the wire in both directions.
The two framings are indistinguishable on the wire, so there is no safe auto-detect. The fix has to ship together with the relay bump: builds without it stop working the moment the relays move, and builds with it cannot talk to the relays until then.
🤖 Generated with Claude Code
Activity