Skip to content

spf/moqt: moq-relay 0.14.17 frames LARGEST_OBJECT as bare varints; the codec decodes and encodes it length-prefixed #45

Closed

Description

@mmcc

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_OK for any track with content and closes the session, and
  • the publisher's own SUBSCRIBE_OK / REQUEST_OK are misparsed by the relay once a track has content, because the publisher reports LARGEST_OBJECT too.

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_OBJECT is a bare Location, two consecutive varints (Group, Object), with no Length prefix. Draft-14 through -16 keep the length-prefixed form.
  • SUBSCRIBE_OK carries LARGEST_OBJECT on 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 Location changed. 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)

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: in SUBSCRIBE_OK and in the REQUEST_OK for REQUEST_UPDATE, whenever getLargestObject() 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_PARAMETERS with StartGroup=1 (moq-dev/moq#3325), replacing the relative-group 1 pull the test hub encodes. #fillRequested and 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 a LARGEST_OBJECT advertised, 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

  1. On draft-17 and newer, write and read LARGEST_OBJECT as two bare varints. The engine only speaks draft-20, so the two helpers can simply be replaced; mmcc/moq-resilience still shows the bare writeLocation / readLocation form this codec used before the moqt-20 cutover.
  2. 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.
  3. Update relay-hub.ts to send the 0.14.17 pull (Next Object + FILL_PARAMETERS StartGroup=1) so the fill-serving path is exercised in CI.
  4. Run a live pass against moqdev/moq-relay:0.14.17 covering playback of a track with content, and publishing where the relay re-subscribes after content exists, so LARGEST_OBJECT is 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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions