fix(spf): end published tracks with PUBLISH_DONE track ended

Merged
MM
1mo ago
+679-214

Summary

moq-relay 0.17.0 (sjc.relay.mux.global) reports a publisher's bare FIN on an upstream subscription as PUBLISH_DONE status 0 "internal error" to every viewer. Since this branch ended tracks with a bare FIN, every intentional unpublish looked like a failed track. The publisher now sends PUBLISH_DONE (TRACK_ENDED) with an exact Stream Count before the FIN, as draft-20 §10.12 and MSF §11.3 intend. The relay then forwards "track ended".

Changes

  • Every track end (unpublish, engine teardown, the session's close drain) sends each subscription PUBLISH_DONE with status TRACK_ENDED and its Stream Count, then FINs it.
  • The Stream Count is exact, because a relay that receives more streams than declared may close the session. Track publishers count the data streams each subscription received, at the subgroup-header commit, and the session adds the fill streams it opened. A track registered without a counter reports the 2^64−1 "unknown" sentinel, which encodePublishDone can now write.
  • A subscription the relay superseded with a newer one still ends with a bare FIN. That is not a track end, and no status code fits it.
  • The test relay hub forwards the publisher's status downstream (a bare FIN becomes INTERNAL_ERROR, matching sjc), and its trackEnds record now carries the status. The sandbox loopback relay accepts PUBLISH_DONE then FIN as a clean end.
  • The session docs and internal/design/spf/features/moq-publish.md drop the old "a track ends by FIN alone" rule.
Compatibility

Older moq-relay builds abort a track on any byte after SUBSCRIBE_OK. relay.mux.dev still runs one: with this change, its viewers lose every track on the first PUBLISH_DONE, including the §11.3 end-of-broadcast catalog. Those builds are no longer supported.

encodePublishDone lives in network/moqt (the playback branch's wire layer). The change only widens streamCount to number | undefined, so base syncs should merge cleanly.

Testing

  • pnpm -F @videojs/spf test: new coverage for per-alias stream counts, fill streams counted in the Stream Count, the unknown-count encoding, and the teardown paths asserting PUBLISH_DONE TRACK_ENDED with exact counts. 2722 tests passed in three consecutive runs. One earlier run had a single failure that didn't reproduce (test name not captured), so treat it as a possible flake.
  • pnpm lint and pnpm typecheck pass after a clean pnpm build:packages.
  • Verified live on sjc.relay.mux.global: on unpublish, viewers got the end-of-broadcast catalog, then PUBLISH_DONE status 2 "track ended" on both catalog and audio (previously status 0 "internal error"). After TRACK_ENDED, the relay also appends its own end-of-track status object, which the SPF player already skips.
  • The sandbox loopback relay change hasn't been run in a browser (sandbox templates aren't covered by typecheck or tests).

🤖 Generated with Claude Code


Summary by cubic

Ends published tracks with PUBLISH_DONE (TRACK_ENDED) and an exact Stream Count before each FIN, so intentional unpublishes no longer reach viewers as status 0 "internal error" on moq-relay 0.17.0. Previously a bare FIN ended tracks, which the relay reported as a failed track. Relay pulls whose fill cannot be reset reliably are also served now, instead of refusing the whole SUBSCRIBE with NOT_SUPPORTED.

  • Per subscription, data streams are counted at the subgroup-header commit, the session adds its fill streams, and a track without a counter reports the 2^64−1 unknown sentinel.
  • Every track now also closes its data streams before PUBLISH_DONE per §10.12: the open group gets a FIN, then a bounded flush (half the close drain window), then destroy() on the publisher.
  • A subscription the relay superseded with a newer one still ends with a bare FIN, since that is not a track end and no status fits it.
  • The test relay hub and the sandbox loopback relay now forward the publisher's status downstream; the loopback relay reports INTERNAL_ERROR on any malformed post-SUBSCRIBE_OK frame.
  • Nonempty fill requests no longer require WebTransport's commit(): the session serves the subscribe, writes the FETCH_HEADER where it can, and resets the fill as before. A reset may discard the header, which leaves the subscriber's join at the next group boundary.
  • Fill fetch streams count toward the Stream Count wherever the session opens one, even when the header may not survive the reset; a fill still opening when the track ends is reset headerless and left uncounted.
  • Older moq-relay builds abort a track on any byte after SUBSCRIBE_OK; with this change, they are no longer supported.
  • encodePublishDone's stream count widens from number to number | undefined, so base syncs should merge cleanly.