feat(spf): speak moq-transport draft-20 (moqt-20)
Merged
MM
3mo ago+15517+15517+01234567890123456789012345678901234567890123456789-615-615-012345678901234567890123456789
Summary
Cut the MoQ playback stack over from moq-transport draft-19 to draft-20 (moqt-20), the version moq-relay 0.14.14 now speaks across the fleet. Vendors the draft texts under internal/specs/moq/ so the codec can be reviewed against the spec offline, and records the migration plan and live interop findings under .agents/plans/.
Changes
- ALPN
moqt-20; PUBLISH_STATE_NOTIFY, FILL_PARAMETERS and INCLUDE_PROPERTIES decode instead of closing the session; End of Timed-Out Range is read on fetch streams; the codes draft-20 removed (SUBSCRIPTION_ENDED, INVALID_JOINING_REQUEST_ID, VERSION_NEGOTIATION_FAILED) are gone. - LOCATION_FILTER is draft-20's length-counted field list. The
LocationFilterunion is nownone/next-object/relative-group/absolute; an open-ended absolute{0,0}normalizes to no filter per ยง5.1.2. - FETCH takes the SUBSCRIBE body with its range in LOCATION_FILTER; the Standalone / Joining structures are gone.
- The catalog joins with a
relative-group 1subscription and no FETCH. Draft-20 relays no longer replay the current group for a Next Object subscription, and against moq-relay the joining FETCH never carried catalog data, so this is what keeps catalogs resolving. Deltas apply only against the independent object of their own group. - LARGEST_OBJECT and INCLUDE_PROPERTIES are framed length-prefixed to match moq-relay (moq-dev/moq#3255 records the disagreement with the spec text); the framing is byte-pinned against moq-dev's vector.
- Two pre-existing bugs fixed along the way: REQUEST_UPDATE now consumes its own Request ID (ยง10.1), and PUBLISH_DONE's 2^64โ1 "could not count" Stream Count sentinel decodes as
undefinedinstead of failing the session. - Sandbox templates and comments move to draft-20 wording; the loopback relay emits the loc-04 timestamp id.
Implementation details
- Hard cutover, no draft-19 fallback: the fleet (mux.global and relay.mux.dev) is uniformly on 0.14.14.
MOQT_PROTOCOL_IDis the single offered protocol. - Video and switch handoffs keep their semantics under the new names (
relative-group 0); audio'snext-objectjoin now starts at the live edge rather than the group start, which the latency controller absorbed in testing. - Fills are decoded but not requested; fill-stream routing is deferred (Phase 6 in the plan). An unsolicited fetch stream is dropped, not fatal.
- The spf size script predates the Vite+ move and cannot run; measured with rolldown directly, the MoQ engine entry grows ~0.1 KB min+gzip.
Testing
pnpm -F @videojs/spf testโ node projects 69 files / 1242 tests, browser projects 49 files / 765 tests (11 skipped);pnpm typecheck,pnpm lint,pnpm check:workspacepass.- Live against sjc.relay.mux.global (moq-relay 0.14.14) with a synthetic draft-19 publisher from the
mmcc/moq-publishersandbox:moqt-20negotiated, catalog resolved from therelative-group 1replay (object 0 delivered), anext-objectcatalog subscription confirmed strict (empty stream), video join delivered from the IDR at object 0 with LARGEST_OBJECT{35,28}decoding correctly, player stable at the 0.5 s latency target. Details in.agents/plans/moq-transport-20-migration.md. - relay.mux.dev could not be tested: its certificate expired 2026-08-26.
๐ค Generated with Claude Code
Summary by cubic
Cuts the MoQ playback stack from moq-transport draft-19 to draft-20 (moqt-20), the version moq-relay 0.14.14 speaks across the fleet, with no draft-19 fallback. Vendors the draft texts under internal/specs/moq/ for offline review and records the migration plan and live interop findings under .agents/plans/.
Protocol changes
- ALPN moves to
moqt-20;PUBLISH_STATE_NOTIFY,FILL_PARAMETERS, andINCLUDE_PROPERTIESdecode instead of closing the session. LOCATION_FILTERbecomes draft-20's length-counted field list (none/next-object/relative-group/absolute); FETCH takes the SUBSCRIBE body with its range inLOCATION_FILTER.- Catalogs now resolve via a
relative-group 1subscription with no FETCH, since draft-20 relays no longer replay the current group for Next Object subscriptions. - LARGEST_OBJECT and INCLUDE_PROPERTIES are framed length-prefixed to match moq-relay.
- Audio's
next-objectjoin starts at the live edge instead of the group start; fills decode but aren't requested, and unsolicited fetch streams are dropped, not fatal. - REQUEST_UPDATE consumes its own Request ID, and PUBLISH_DONE's Stream Count decodes as
undefinedonly for the exact 2^64โ1 sentinel โ any other count past the 2^53โ1 ceiling stays a protocol error. - A reordered independent catalog object from an older group is dropped rather than rolling the presentation back, and the catalog's base group advances only after its independent object parses.
- Accepting an incoming PUBLISH sends a bare PUBLISH_OK; parameters on it would be a protocol violation.
Testing
- Full test suite, typecheck, lint, and workspace checks pass.
- Live interop against sjc.relay.mux.global (moq-relay 0.14.14) negotiated
moqt-20, resolved the catalog from therelative-group 1replay, and delivered video from the IDR; relay.mux.dev was skipped due to an expired certificate.