Repository navigation
quest(m1): plan frame arrival stamps for TS export lateness #6147
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,46 @@ | ||
| # [M] Frames carry their local arrival time | ||
|
|
||
| ## Goal | ||
|
|
||
| Each frame a moq-net reader receives carries the local instant it landed in | ||
| this node's cache, so a consumer judges lateness from that stamp instead of | ||
| the moment it happened to poll. TS export uses it, so a stall of the whole | ||
| path no longer lets held frames out past their deadline: the ignored arm | ||
| `a_path_stall_drops_what_it_made_late` in `rs/moq-mux` passes and loses its | ||
| `#[ignore]`. | ||
|
|
||
| Non-goals: wall-clock or cross-hop provenance | ||
| ([received timestamps are media time](/quest/m1/lite-time-provenance.md)), | ||
| and any wire change. | ||
|
|
||
| ## Plan | ||
|
|
||
| Found by the TS recovery arms | ||
| ([moq-dev/moq#6139](https://github.com/moq-dev/moq/pull/6139)): the export | ||
| assumes a frame arrived when it last found the source empty, and during a | ||
| total stall nothing wakes it, so that guess can lag the real arrival by a | ||
| delay or more. Treating a poll after `Pending` as "arrived now" was tried and | ||
| reverted: it breaks the `two_legs_*` tests, because a caller polling on its own | ||
| cadence judges arrivals differently from one polling after every frame. | ||
|
|
||
| Decided by the maintainer on 2026-10-20 (`/quest-plan`): | ||
|
|
||
| - **Per frame**, not per group: frames in a group arrive over time, so | ||
| lateness is per frame. The cost is one `moq_clock::Instant` per cached | ||
| frame. | ||
| - **Stamped on completion**: when the frame's last byte lands in this node's | ||
| cache, the earliest an exporter can emit it. A locally published frame and | ||
| a backfilled (fetched) frame are stamped the same way, when they enter the | ||
| cache. | ||
| - **Accessor only**: `frame::Frame` keeps the stamp in a private field read | ||
| through `Frame::arrived() -> moq_clock::Instant`, with a constructor, rather | ||
| than a public settable field or a separate reader method. Adding a private | ||
| field breaks struct literals of `Frame`, so `rs/moq-net/MIGRATE.md` gets an | ||
| entry. | ||
| - **Rust only**: the only consumer is the Rust TS export. `@moq/net` mirrors | ||
| it when a JS consumer needs it. | ||
| - The stamp reads the ambient `moq_clock`, so simulated tests control it. | ||
|
|
||
| ## Related | ||
|
|
||
| - [Loss and recovery tests](/quest/m1/ts-reliability/recovery.md) - the arms that found this, and the ignored arm it un-ignores | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The Rust-only scope leaves the same defect in the browser stack:
js/hang/src/container/consumer.tscomputesarrival = now()only afterreadFrame()resolves (lines 220-223), then uses that value for jitter classification (lines 247-252). If the JS event loop stalls while frames accumulate in@moq/net, those frames are likewise treated as newly arrived when eventually read. Add the cache-completion stamp tojs/netand consume it here rather than deferring the mirror; the repository also requiresrs/moq-netAPI changes to be synchronized withjs/net.AGENTS.md reference: AGENTS.md:L105-L110
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Declining: "Rust only" was settled by the maintainer in the
/quest-planinterview (recorded in the PR body), and the JS consumer cited here does not have the defect this quest fixes.#runGroupinjs/hang/src/container/consumer.tsspawns one task per group that awaitsreadFrame()back to back, sonow()runs within a microtask of the frame completing in@moq/net's cache. The Rust TS export's problem is different: it polls on its own cadence and guesses arrival from the last time it found the source empty, which nothing refreshes during a total stall.The quest keeps the mirror deferred until a JS consumer actually needs it, and
AGENTS.md's sync table applies to the implementation PR if it changes the shared API.(Written by Claude Opus 5.5)