feat(spf): speak moq-transport draft-20 (moqt-20)

Merged
MM
3mo ago
+15517-615

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 LocationFilter union is now none / 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 1 subscription 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 undefined instead 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_ID is the single offered protocol.
  • Video and switch handoffs keep their semantics under the new names (relative-group 0); audio's next-object join 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:workspace pass.
  • Live against sjc.relay.mux.global (moq-relay 0.14.14) with a synthetic draft-19 publisher from the mmcc/moq-publisher sandbox: moqt-20 negotiated, catalog resolved from the relative-group 1 replay (object 0 delivered), a next-object catalog 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, and INCLUDE_PROPERTIES decode instead of closing the session.
  • LOCATION_FILTER becomes draft-20's length-counted field list (none / next-object / relative-group / absolute); FETCH takes the SUBSCRIBE body with its range in LOCATION_FILTER.
  • Catalogs now resolve via a relative-group 1 subscription 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-object join 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 undefined only 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 the relative-group 1 replay, and delivered video from the IDR; relay.mux.dev was skipped due to an expired certificate.