Repository navigation
feat(net)!: writing a group needs no invented start, and its end has one word - #8961
Conversation
Quest-Claim: 4eaa21678156a7a0
…inish, fail ends a track in error, and Fill splits groups from lookups Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…rack Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ames Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes
I reviewed the full branch at d4d9ec7. That covers the moq-net model changes, including track.rs, whose diff I pulled separately because it was too large for the PR diff file. It also covers the session and production callers and the @moq/net changes. The 200+ mechanical rename sites I spot-checked rather than read line by line.
append_group(None): this starts the group atTrackState::next_key()(max_key + 1, or 0). Removing the overflow filter is safe:create_group,append_group, and fill accepts all refuseu64::MAX, somax_keynever reaches it.finish_sharedalready relied on the same invariant.- Group ends renamed:
group::Producer::close()→finish(), andfinish(end)→finish_at(end). An old call fails to compile because the arity changed. I found no remaining two-argumentfinish_at/finishAtcallers and no references toappend_nextorFill::timein code. track::Producer::fail: this declaresset_end(next_key, Some(err))and consumes the producer asfinishdoes. The wire-forwarding path keeps its received-copytailhandling through the crate-privateend_at. The moq-mux, moq-audio, and moq-archive callers end at the same live edge they computed by hand before.Fillenum:FillGroupskeeps the run API, andFillLookupexposes onlytime,priority,max_delay, andaccept. In moq-archive, theAskerthat makesdrop_groups/refuse_groupsno-ops for a lookup matches the old behavior:owed()was always empty for a lookup. moq-ffi, moq-c, moq-transcode, and the sessions drop lookups unanswered, as the PR says.- JS:
fail(error)declares at#receivedand mirrorsfinish()'s no-op guard.Fillis a union told apart bykind. The lite and ietf subscribers and the interop clients close or skip lookups.
claude-opus-5-5 | 𝕏
kixelated
left a comment
There was a problem hiding this comment.
Automated review by review (OpenAI) · d4d9ec771ac6cf5e390dbbde5503c519d957efbb
No Rust runtime blocker found in the group/end changes. Choosing the next key and claiming it under the same lock is better than the old call-site arithmetic. fail preserves the drain-before-error path, and splitting Fill keeps the archive's time lookup while making unsupported lookups explicit at the wire and binding boundaries.
One migration safeguard worth adding: plain JS callers of finishAt(end, error) don't get TypeScript's arity error. They now silently declare clean EOF. At js/net/src/track.ts:2210, consider rejecting a supplied legacy error argument with a message pointing to fail(error) (or preserving the old overload for one release). Throwing is safer than silently claiming success when the requested error can't be represented at an arbitrary end. Static review only.
|
Maintainer decision (2026-11-16, /quest-run): (Written by Opus 5.5) |
|
Maintainer decision (2026-11-16, /quest-run), refining the one above: (Written by Opus 5.5) |
The maintainer settled that a group's start is always stated: append_group takes a Timestamp, converted into the track's timescale as write_frame does, and an untimed track takes Timestamp::unscaled(key). A start that doesn't match its track is TimestampMismatch. The optional start is gone, along with its implicit 'previous start + 1'. Tests that count groups use the restored test-only append_next (and the integration tests' AppendNext trait). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Production callers pass the timestamp they already hold (moq-mux's catalog, container, fmp4 and SI writers, moq-json's producers, moq-stats), moq-ffi and moq-c compute their start-less append in the track's timescale, and tests on timed tracks state their starts in milliseconds or microseconds. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ename Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Applied the refined decision at 712354c: On the earlier review's (Written by Claude Opus 5.5) |
kixelated
left a comment
There was a problem hiding this comment.
Automated review by review (OpenAI)
Head: 712354c5f4d4dcc0afb33b2da464b2047562cd16
No new blocker in the Rust timestamp migration. The mux and CMAF callers rescale the same timestamp they previously used to compute the group key; explicit pending starts still use create_group. The catalog and SI paths pass the bumped timestamp through, so same-tick updates still get distinct keys. The C and UniFFI compatibility shims retain their old synthetic numbering and the bindings quest now tracks removing it.
The earlier JS migration caveat still stands: untyped finishAt(end, error) calls silently declare a clean end. Consider rejecting the old argument rather than dropping an error. Static review; I did not run tests.
# Conflicts: # rs/moq-cli/src/play/video.rs # rs/moq-ffi/src/media.rs # rs/moq-video/src/decode/consumer.rs
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes
Since d4d9ec7, append_group takes a required Timestamp instead of an optional u64. I checked the moq-net implementation and every non-test production caller. The test, bench and fuzz migrations I spot-checked.
- Required
Timestampstart:append_grouprescalesstartthroughInfo::rescaleand passes the key to a privateappend_key. A start that doesn't match the track is refused before any group exists.write_framenow passes the rescaled timestamp, and rescaling it again changes nothing. - Test-only
append_next: restored aspub(crate)undercfg(any(test, feature = "fuzz")). It callsappend_key(next_key())directly, so noTimestampround trip is needed. The integration tests'AppendNexttrait buildsTimestamp::new(key, timescale), orunscaledon an untimed track. - moq-mux callers: the container producer, fMP4 import, catalog producer and SI writer now pass the timestamp, not the precomputed key.
start::opens,start::after,start::nextandstart::beforealready return a timestamp that rescales to that key, so the group keys don't change. - moq-json and moq-stats: the snapshot, window and stream producers now take the converted key, and
largestfollowsgroup.start. moq-stats previously passedtimestamp.value()without converting, so this fixes a real scale bug. - moq-crypto:
e2ee::track::Producer::append_grouprescales beforeclaim.allocate, so a refused start allocates nothing. - moq-ffi and moq-c: the private
next_startnow returnsTimestamp::new(largest + 1, timescale), orunscaledon an untimed track. This exactly matches the key used before. - Quests:
quest/m2/time-addressing/bindings.mdnow recommends a required timestamp start for the bindings.
claude-opus-5-5 | 𝕏
# Conflicts: # rs/hang/src/catalog/consumer.rs
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes
Since 712354c, the only new commit merges origin/main. I checked its conflict resolutions, and that the code main brought in uses this PR's API.
- Conflict resolutions:
moq-cliplay/video.rsandmoq-ffimedia.rskeep main's rewritten tests and end their groups withfinish(). Main deleted themoq-videodecode/consumer.rstests that used the oldappend_group. - Tests from main migrated: the new tests now end groups with
group.finish()in place ofclose(), andmin_age_join.rspasses aTimestamp::from_millisstart toappend_group. That covers the min-age join tests intrack.rs, the finished-track fetch tests inresume.rs,claim_continues'Worker::writeand the newmin_age_join.rs. None of the lines the merge adds callfinish_at(end, err),finishAt(end, error)orFill::time.
claude-opus-5-5 | 𝕏
# Conflicts: # quest/m2/README.md
# Conflicts: # rs/moq-boy/src/input.rs
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes
Since bc478b2, the only new commits are two merges of origin/main. I reviewed how their conflicts were resolved and checked that the code main brought in uses this PR's API. I checked by reading the code only. The Quest check is the only CI that has run on 25c7454 so far, so nothing has compiled or tested the merged code yet.
- Catalog consumer tests resolved: in
rs/hang/src/catalog/consumer.rsandrs/moq-ffi/src/media.rscatalog_tests,mainchanged catalog consumers to returnmoq_json::Timed. The tests now pass aTimestamp::from_millis(ms)start toappend_group, end each group withgroup.finish(), and read the payload through.value. - Quest index resolved:
quest/m2/README.mddrops the deletedgroup-api.mdlink along withmain's removal ofreconnect-off.md. - Merged code checked: none of the lines the merges add call
group.close(), pass an integer toappend_group, call two-argumentfinish_at/finishAt, or useFill::time.
claude-opus-5-5 | 𝕏
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes
Since 25c7454, the only new commit is a merge of origin/main at ec04746, which brings in #8936. I reviewed how its one conflict was resolved and checked that the code main brought in uses this PR's API.
moq-boyinput tests resolved:mainreplaced the session-tracksendhelper with aViewerthat publishes commands on acommandtrack with aTimescale::MILLItimescale. The resolved tests callappend_group(Timestamp::from_millis(1)), which lands on the same key 1 asmain'sappend_group(1), and end the group withgroup.finish().viewer.at = 1makes the snapshot's next append land at key 2, after the stalled group.- Merged code checked: none of the lines the merge adds call
group.close(), pass an integer toappend_group, call two-argumentfinish_at/finishAt, or useFill::time.
claude-opus-5-5 | 𝕏
|
Maintainer decision (2026-11-16, /quest-run): ✅ no runtime guard for an untyped-JS caller still passing an error to (Written by Opus 5.5) |
|
Head 5210fbb already implements #8961 (comment): (Written by Opus 5.5) |
Takes main's group::Producer::finish_at(end)/finish() names (#8961), with JS mirroring them as finishAt(end)/finish(), keeps main's Announce Stream (0x3) while dropping Padding (0x2), and drops main's edits to the re-offer and judged-range tests this branch removes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Finishes quest/m2/group-api.md: a publisher opens a group at a stated
Timestampstart, ends a group withfinish, ends a track in error with a call of its own, and a fill handler matches a run of groups apart from a time lookup. The quest file and every link to it are deleted.Summary
track::Producer::append_group(start: Timestamp): the start is required and is aTimestamp, not a bareu64. A timed track converts it into its timescale aswrite_framedoes; an untimed track takesTimestamp::unscaled(key); a start that doesn't match its track, or that its scale can't hold, isTimestampMismatch, refused before any group exists. Production callers now pass the media timestamp they already hold: moq-mux's catalog, container, fMP4 and SI writers, moq-json's snapshot, window and stream producers, and moq-stats, which before passedtimestamp.value()and so assumed the caller's scale matched the track's. moq-ffi's and moq-c's privatenext_startstays for their start-lessappend_group()/track_group, now returning the next key as aTimestampin the track's timescale. Tests that count groups keep the test-onlyappend_next(and the integration tests'AppendNexttrait), which appends at the next key without a timestamp round trip; tests on timed tracks state their starts withfrom_millis/from_micros.group::Producer::close()isfinish(), andfinish(end)isfinish_at(end), matchingtrack::Producerand what moq-ffi and JS already say.finish()'s docs say that readers cannot tell the group is whole, since onlyfinish_atdeclares the end a media reader checks. About 1,300 call sites were renamed, guided by the compiler.track::Producer::finish_at(end)is always a clean end.track::Producer::fail(self, err) -> Result<Finished>ends the track witherrat its live edge, the errored counterpart offinish: readers get every group below the end, thenerr. A session forwarding a wire end that carries an error, possibly ahead of the live edge, uses the crate-privateend_at(end, error). The three production callers (moq-muxend_with, moq-audiofail_track, moq-archive's replayEnd::Error) each computed the live edge by hand and now callfail.track::Fillis an enum:Fill::Groups(FillGroups), today's run of groups minustime(), orFill::Lookup(FillLookup), which has onlytime() -> u64,priority,max_delay, andaccept. A lookup has nowanted,drop_groups,end, oris_wantedto misuse. moq-archive serves both kinds. moq-transcode, moq-ffi, moq-c, and moq-net's own lite and ietf sessions drop a lookup unanswered as soon as they receive it. Before, they pushed it into a fill run that ended immediately, so the outcome is the same.e2ee::group::Producer::close()isfinish(), ande2ee::track::Producer::append_grouptakes aTimestampstart like the track it wraps, rescaled before it allocates so a refused start allocates nothing. This also settles that item of quest/m3/e2ee-format.md.@moq/net):Track.Producer.finishAt(end)drops itserrorparameter, andfail(error): Finishedends at the live edge.Track.FillisFillGroups | FillLookup, told apart bykind: "groups" | "lookup", the codebase's union convention. The lite and ietf sessions close a lookup at once. Tests that needed an errored end past the live edge use the received-copy hook, the only path that produces one now.doc/lib/rs/moq-net.mdanddoc/lib/js/net.mdname the new calls. Quests that cited the old names were updated (refresh-interval,archive-time-followups,e2ee-format, the m2 README).Impact
Public API: breaking in Rust (
moq-net,moq-crypto) and JS (@moq/net). moq-ffi, moq-c, and every binding keep their API: they already served only runs of groups, ended groups withfinish(), and theirappend_group()takes no start. Wire: none.Migration:
track::Producer::append_grouptakes aTimestamp: pass the group's first frame's timestamp on a timed track (it is converted into the track's timescale), andTimestamp::unscaled(key)on an untimed one.append_group(key)becomesappend_group(Timestamp::unscaled(key))only where the track has no timescale.group::Producer, callfinish()where you calledclose(), andfinish_at(end)where you calledfinish(end).track::Producer::finish_at(end, None). Forfinish_at(live_edge, Some(err)), calltrack.fail(err); it consumes the producer asfinishdoes, so usetrack.clone().fail(err)to keep a handle.Requests::requested_fill()returnstrack::Fill. MatchFill::Groups(fill)where you used the fill, andFill::Lookup(lookup)where you checkedfill.time().is_some().FillLookup::time()returnsu64. A handler that cannot resolve times drops the lookup.e2ee::group::Producer::close()isfinish(), ande2ee::track::Producer::append_grouptakes aTimestampas moq-net's does.@moq/net: replaceproducer.finishAt(end, error)withproducer.fail(error)at the live edge.Track.Fillis a union: checkfill.kind === "lookup"where code checkedfill.time !== undefined, and narrow toFillGroupsbefore callingwanted,dropGroups,start, orend.Decisions
Maintainer, 2026-11-16 (first, refined), reversing the group-api Plan item "append_group takes an optional start":
append_group(start: Timestamp), required, converted into a timed track's timescale aswrite_framedoes,Timestamp::unscaled(key)on an untimed track,TimestampMismatchwhen it doesn't match (rejected:append_group(start: u64); an optional start, whetherNonemeant the next counter on untimed tracks only, the previous group's declared end on timed tracks, or largest + 1 as first merged here; an optional frame timestamp to drop theTimestamp::unscaled(group.start)restatement). Reason:Nonemeant the previous group's start + 1, a counter on an untimed track but neither the previous group's end nor a media time on a timed one, which the maintainer found confusing; and noOption<Timestamp>anywhere in the API.Taken while applying it, open to review:
append_nextstays test-only (cfg(any(test, feature = "fuzz"))), and appends at the next key directly rather than through aTimestamp, so it reaches the reserved key'sBoundsExceededon a timed track whose keys aTimestampcan't hold. Other crates' tests that used the next-key idiom spell it out (Timestamp::from_millis(track.largest().map_or(0, |l| l.group + 1))) rather than gaining a shared public helper, which would be the rejected implicit next start under another name.append_group()/track_groupthis PR: changing them is a breaking change in every binding. quest/m2/time-addressing/bindings.md, the bindings' breaking rename, now recommends giving them a required timestamp start.appendGroup()still takes no start; JS has no start to mirror until quest/m2/time-addressing/js.md rekeys its groups by start.Taken without asking earlier (the user was away), each open to review:
fail, ends at the live edge with no end argument, and consumes the producer to returnFinishedlikefinish. All three production callers wanted the live edge. The only caller that needs an end ahead of the live edge is the relay forwarding a wire end, and it uses the crate-privateend_at.FillGroupsandFillLookup, nottrack::fill::{Groups, Lookup}. The same names work in JS, whereTrack.Groupsis already taken by the subscription range type.FillLookupexposes nostart/end: the answer is "the group containing the time", which the handler finds from its source. A test-onlyspan()checks what a lookup was asked over.MoqFilland fill handle now wrapFillGroups), and gain nofail: no binding has an errored end today, and nothing downstream asks for one. Exposing lookups to bindings stays with quest/m5/archive-time-followups.md, whose wording now namesFillLookup. With no binding API change, no bindingMIGRATE.mdnote rides this PR.fail()is a no-op once an end is declared or the track closed, as JSfinish()is. Rust'sfailrefuses withClosed, as Rust'sfinishdoes. Each mirrors its own language'sfinish.rs/moq-mux/src/start.rsstays whole: every helper in it computes a timed track's start from a timestamp, and none existed only for the next-start idiom.container::Producer::next_startstays too, as the floor a seek clamps to.Follow-ups
append_group(), mirroring Rust. Open decision: whether to take that in the bindings' rename (recommended) or keep the start-less binding append.Validation
After the required-start change (merged with main through ec04746;
just checkreran on each merge):just checkover the branch diff passes every module;cargo nextest run --workspace --tests --all-featuresran 13,910 tests with 13,908 passing and two moq-audio PCM round-trip tests failing only under that full-workspace load (they pass alone, three runs out of three);just test interop --allpasses. To find every timed track handed an unscaled start, a temporary build ofappend_grouplogged each such caller (with#[track_caller]) instead of refusing it, over the whole test suite and every bench in--testmode; each logged site now states its start in the track's unit.Before it:
just ciover the branch diff: every module passes excepttest py. Its one failure,test_socket.py::test_abort_and_endpoint_close_are_errors, is a known flake (quest/m0/test-flakes-3/py-socket-abort.md, fixed by moq-dev/moq#8900). It fails 22 of 40 runs alone here, and this diff touches no socket code. Rust: 12,855 tests passed. JS:@moq/net's 3,327 tests passed.no-asyncclippy and rustdoc with-D warningsare clean.just test interop --all: all checks passed. That runs the real Rust, JS (node and bun), Python, Go, and C clients against each other over every lite version and moq-transport, including thedrop,tail,finish, track-replacement, and socket scenarios, whose Rust and JS clients this PR edits.u64::MAXis refused; a group ended byfinish()reads whole withend() == None, whilefinish_atdeclares its end; a track ended byfailserves every group below its end, then yields the error, and refuses a second end. In JS: a failed track keeps its history, andfailends at the live edge and leaves an end already given.Models
Size: L
Implementer: Claude Code, claude-opus-5-5, high effort
Implementer: Claude Code, claude-opus-5-5 (iterate, M)
(Written by Claude Opus 5.5)
Review
Rewritten by
quest reviewafter each round.Head: 5210fbb
Base: origin/main at ec04746
Risk: high,
The branch changes public Rust and JavaScript track/group APIs, which can break downstream callers and require coordinated caller updates or an API rollback.Classified: medium by default
Reviewer: Codex, gpt-6.1-sol, xhigh effort
Session:
01a1e6df-6cef-7033-bbd3-500bc8c7cfa6, round 2Score: 9/10,
Static review of the incremental changes found no actionable regressions; builds and tests were not run, as instructed.Raised the risk to high:
The branch changes public Rust and JavaScript track/group APIs, which can break downstream callers and require coordinated caller updates or an API rollback.Rounds: 5; first round 0; findings 0: fixed 0, refuted 0, open 0
Findings: none