Repository navigation
feat(spf): speak moq-transport draft-20 (moqt-20) - #41
Conversation
Vendor draft-ietf-moq-transport-20, draft-ietf-moq-loc-04 and draft-ietf-moq-msf-01 under internal/specs/moq with provenance, point AGENTS.md at them, and record the draft-19 to draft-20 migration plan grounded in moq-relay 0.14.14's implementation.
Cut the MoQ stack over from draft-19 to draft-20, matching moq-relay 0.14.14: - ALPN moqt-20; decode PUBLISH_STATE_NOTIFY (0x22), FILL_PARAMETERS (0x23) and INCLUDE_PROPERTIES (0x35); read End of Timed-Out Range (0x20C); drop SUBSCRIPTION_ENDED, INVALID_JOINING_REQUEST_ID and VERSION_NEGOTIATION_FAILED. - LOCATION_FILTER is the length-counted field list (none / relative-group / next-object / absolute); FETCH takes the SUBSCRIBE body with its range in LOCATION_FILTER. - LARGEST_OBJECT and INCLUDE_PROPERTIES are framed length-prefixed, as moq-relay does (moq-dev/moq#3255 records the spec conflict). - The catalog joins with a relative-group 1 subscription and no FETCH: draft-20 relays no longer replay the current group for Next Object, and the joining FETCH never carried catalog data. - REQUEST_UPDATE consumes its own Request ID (section 10.1); PUBLISH_DONE's 2^64-1 Stream Count sentinel decodes as undefined instead of failing the session.
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
📦 Bundle Size Report🎨 @videojs/html — 1 small size change
Presets (7)
Media (20)
Players (5)
Skins (37)
UI Components (49)
⚛️ @videojs/react — no changesPresets (7)
Media (23)
Players (5)
Skins (26)
UI Components (39)
🧩 @videojs/core — no changesEntries (76)
🏷️ @videojs/element — no changesEntries (2)
📦 @videojs/store — no changesEntries (3)
🔧 @videojs/utils — no changesEntries (13)
📦 @videojs/media
Entries (21)
📦 @videojs/spf — 1 small size change
Entries (11)
ℹ️ How to interpretEach entry is independently bundled, minified, and brotli-compressed. Initial size includes its static import graph; lazy dynamic chunks are reported separately. Entries are not additive because their dependency graphs overlap. Preset rows represent realistic combined bundles. Changes of 300 B or less across initial, lazy, and total size are collapsed, not discarded. Run |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e41254377d
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| (its Appendix A.1 is the authoritative change list). The code on `mmcc/moq` | ||
| and `mmcc/moq-publisher` pins draft-19 (`MOQT_PROTOCOL_ID = 'moqt-19'`). |
There was a problem hiding this comment.
Remove the completed temporary migration plan
This completed migration checks in a 428-line temporary plan that still states the code pins moqt-19, although this commit switches it to moqt-20. Once merged, that stale implementation artifact will mislead future retrieval-led work; remove it and also delete the new reference from moq-engine-implementation.md, as repository guidance explicitly requires temporary .agents/plans/ notes to be deleted before merge.
AGENTS.md reference: AGENTS.md:L64-L70
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Keeping the plan on this branch deliberately: the PR targets the long-lived mmcc/moq feature branch, which already carries .agents/plans/moq-engine-implementation.md under the same rule, and both get deleted when mmcc/moq merges to main. The stale sentence that said the code still pins moqt-19 is corrected in c1f23df.
There was a problem hiding this comment.
1 issue found across 34 files
Not reviewed (too large): internal/specs/moq/draft-ietf-moq-transport-20.txt (~8,848 lines), internal/specs/moq/draft-ietf-moq-msf-01.txt (~4,144 lines) - if these are generated or fixture files, add them to ignored paths to exclude them from future reviews.
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name=".agents/plans/moq-transport-20-migration.md">
<violation number="1" location=".agents/plans/moq-transport-20-migration.md:17">
P3: This `.agents/plans/` file is committed into the PR even though AGENTS.md (and the file's own header) require temporary plans to be deleted before merge. It also mixes an implementation plan with a completed-work log and live interop results, which README.md says do not belong in the repository. Remove this file from the PR; move durable rationale into `internal/decisions/` or `internal/design/` only if explicitly requested.</violation>
</file>
Tip: cubic can generate docs of your entire codebase and keep them up to date. Try it here.
Re-trigger cubic
| @@ -0,0 +1,428 @@ | |||
| # MoQ transport draft-20 migration plan | |||
There was a problem hiding this comment.
P3: This .agents/plans/ file is committed into the PR even though AGENTS.md (and the file's own header) require temporary plans to be deleted before merge. It also mixes an implementation plan with a completed-work log and live interop results, which README.md says do not belong in the repository. Remove this file from the PR; move durable rationale into internal/decisions/ or internal/design/ only if explicitly requested.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At .agents/plans/moq-transport-20-migration.md, line 17:
<comment>This `.agents/plans/` file is committed into the PR even though AGENTS.md (and the file's own header) require temporary plans to be deleted before merge. It also mixes an implementation plan with a completed-work log and live interop results, which README.md says do not belong in the repository. Remove this file from the PR; move durable rationale into `internal/decisions/` or `internal/design/` only if explicitly requested.</comment>
<file context>
@@ -0,0 +1,428 @@
+only draft-20 peer we talk to, so this plan follows its wire behavior where
+the spec text is ambiguous, and calls out each place it does.
+
+Temporary implementation notes — delete before merge per `AGENTS.md`.
+
+## What changed on the wire (draft-19 → draft-20)
</file context>
There was a problem hiding this comment.
Keeping the plan on this branch deliberately: the PR targets the long-lived mmcc/moq feature branch, which already carries .agents/plans/moq-engine-implementation.md under the same rule, and both get deleted when mmcc/moq merges to main. The stale sentence that said the code still pins moqt-19 is corrected in c1f23df.
- resolve-catalog: an independent catalog object from a group older than the current base is a reordered straggler; drop it instead of rolling the presentation back. - session: accepting an incoming PUBLISH sends a bare PUBLISH_OK. Draft-20 allows subscription parameters only on PUBLISH and REQUEST_UPDATE, and a parameter in the wrong message is a PROTOCOL_VIOLATION (section 10.2.1).
- resolve-catalog: move the base group only after its independent object parsed, so a malformed catalog cannot route the next group's deltas onto the previous catalog. - PUBLISH_DONE Stream Count: only the exact 2^64-1 sentinel reads as unknown; any other count past 2^53-1 stays a protocol error. - moq-session: name the relay fleet the same way in all three comments. - plan: the draft-19 pin is described as the state before this branch.
Brings the publisher stack onto the moq-transport draft-20 (moqt-20) cutover that landed on mmcc/moq in PR #41. Publisher-side ports beyond the textual conflict (the TRACK_PROPERTY block in control-messages.ts): - publish-session: inbound REQUEST_UPDATE consumes its own Request ID (§10.1) — claimed like every other request id, so a reuse is session-fatal; onRequestUpdate reports the updated request's id and the update's own id. - relay-hub test helper: resolves draft-20 Location Filters the way moq-relay 0.14.14 does (relative-group 1 replays the current group, relative-group 0 waits for the next, next-object is strict), pulls upstream with relative-group 1, and sends LARGEST_OBJECT in SUBSCRIBE_OK once a track has content. - raw-peer helper and the byte-pinned SUBSCRIBE vector: the relay's upstream join is now the single field 0x1 (relative-group 1). - moq-publisher sandbox loopback relay: pulls upstream with the same relative-group 1 filter; draft-20 prose. - Tests: REQUEST_UPDATEs use fresh request ids; new coverage for a reused id closing the session. - Prose: draft-19 references in publisher code, tests, and the sandbox template updated; Phase 5 status recorded in the migration plan. Still owed on this branch (Phase 5 of the plan): serving relative-group 1 from the in-progress group's object 0 in track-publisher, LARGEST_OBJECT in the publisher's SUBSCRIBE_OK, and open-and-reset for inbound FILL_PARAMETERS.
Finishes the publisher side of the moq-transport draft-20 migration begun on mmcc/moq (PR #41). Three behaviors the relay's draft-20 upstream join needs: - In-progress-group replay. `track-publisher.ts` retains the current group (keyframe + deltas, bound or not, reset each keyframe) and, on bind, replays it from object 0 under the new alias before continuing live. A subscription joining mid-group — the relay's `relative-group 1` upstream join — now decodes instantly instead of waiting a GOP, and no subgroup stream begins partway through a group (the peer drops those). Group-per-frame tracks keep using `replayLastGroupOnBind`. - LARGEST_OBJECT in SUBSCRIBE_OK. The actor tracks the largest (group, object) it has written on its snapshot; `setup-track-publishers` passes a `getLargestObject` reader into `registerTrack`, and the session reports LARGEST_OBJECT (§10.2.17) in SUBSCRIBE_OK once content exists, omitting it before. Pulled at subscribe time, so no snapshot churn. The sandbox loopback relay's SUBSCRIBE_OK parser now skips the parameter block by parity instead of asserting it is empty. - Inbound FILL_PARAMETERS. `#openAndResetFill` opens a uni stream, writes a FETCH_HEADER carrying the initiating Request ID, and resets it — the §5.1.3.1 minimum for an origin that serves no fills (reset = failure; a FIN would falsely claim an empty range). Wired on the inbound SUBSCRIBE and REQUEST_UPDATE paths, gated on Forward State 1, with FILL_PARAMETERS pulled out of the update's unsupported-parameter set. `encodeFetchHeader` added to `object-stream.ts`. Tests: rewrote the four track-publisher/behavior tests whose documented "join at next keyframe" behavior the replay supersedes; added actor coverage for Largest Object tracking and session coverage for LARGEST_OBJECT in SUBSCRIBE_OK and the fill open-and-reset. All spf test projects pass (node 353, browser 130); typecheck, lint, and format clean. Not yet verified live against the relay fleet.
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 underinternal/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
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.LocationFilterunion is nownone/next-object/relative-group/absolute; an open-ended absolute{0,0}normalizes to no filter per §5.1.2.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.undefinedinstead of failing the session.Implementation details
MOQT_PROTOCOL_IDis the single offered protocol.relative-group 0); audio'snext-objectjoin now starts at the live edge rather than the group start, which the latency controller absorbed in testing.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.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.🤖 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 underinternal/specs/moq/for offline review and records the migration plan and live interop findings under.agents/plans/.Protocol changes
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.relative-group 1subscription with no FETCH, since draft-20 relays no longer replay the current group for Next Object subscriptions.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.undefinedonly for the exact 2^64−1 sentinel — any other count past the 2^53−1 ceiling stays a protocol error.Testing
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.Written for commit c1f23df. Summary will update on new commits.