Repository navigation
feat(ffi)!: bindings address groups by start, not sequence - #8915
Conversation
Quest-Claim: 202fec7cab4c5f86
Rename the group sequence to its start across moq-ffi, moq-c, and every binding, mirroring Rust's group::Info. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
|
No actionable comments were generated in the recent review. WalkthroughThe pull request renames group-position APIs and terminology from sequence to start across the C API, Rust FFI, and Go, Python, and Swift bindings. It updates group accessors, fetch and seek arguments, group creation, and final boundaries. Tests and benchmarks now use group starts. Documentation and planning text also use the updated terminology. The C timestamp guidance adds documented errors for NULL timestamps and invalid scales. Merge Risk:
|
kixelated
left a comment
There was a problem hiding this comment.
Automated review by review (OpenAI)
Reviewed commit: e7c2a2d9fc2492b51e1e4883a165f3b12f2e1b19.
P3: Keep “sequence” in the Kotlin datagram docs. The payload and timestamp docs and the producer docs now call the datagram's own counter “start,” but its public field is still sequence. Restore the datagram wording there so callers don't look for a renamed property.
The group rename is otherwise coherent in the inspected Rust, C and language-binding paths. The two renamed C getters are real symbol breaks, but numeric group starts, exclusive finish semantics, ranges and wire traffic are unchanged. The declared migration at the cut is the right place to call out the symbol and labeled-argument breaks.
Static review only. I didn't run tests or compile the Swift/Kotlin wrappers. I'd run those builds before the cut. COMMENT only, not approval.
There was a problem hiding this comment.
ℹ️ No critical issues. Two doc slips are inline.
Reviewed changes
I read all 62 files. This PR renames a group's sequence to start across moq-ffi, moq-c and every language wrapper, so the bindings match Rust's group::Info.
- moq-ffi: The
sequence()getters on the group producer and consumers becomestart().MoqMediaGroupConfig.sequencebecomesstart. The group-addressing arguments offetch_group,seek,create_group,finish_atand theMoqFillmethods becomestart(orfinal_start). - moq-c:
moq_group_request_sequencebecomesmoq_group_request_startandmoq_publish_group_sequencebecomesmoq_publish_group_start. Other functions only rename their arguments, so the ABI is unchanged. - Wrappers: Python, Go, Swift, Kotlin, Dart (regenerated) and the C++ bench follow the new names. So do their tests, benches and READMEs.
- Docs and quests: The
doc/libpages use the new names, and the finished quest file and its links are removed.
I grepped the repo for the old binding names (.sequence, .Sequence(), sequence=, the old C function names). No callers outside the diff still use them. The remaining hits are JS, datagram fields, or unrelated moq-archive internals.
claude-opus-5-5 | 𝕏
…ing/bindings Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
… README reads whole Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
✅ No new issues found. Both doc fixes from the last review landed.
Reviewed changes
I reviewed what changed since the last Pullfrog review at e7c2a2d: a second merge of main and one fix commit.
- Fixed the datagram docs in Kotlin: The datagram docs in
Aliases.ktsaysequenceagain, which matchesMoqDatagram.sequence. - Fixed the broken README sentence:
py/moq-rs/README.mdnow reads "out of start order". - Resolved the merge with
main: The conflicted tests inrs/moq-ffi/src/media.rsandrs/moq-ffi/src/test.rsusemain's new signatures (MoqJsonSnapshotConsumer::new(.., None)andMoqMediaCatalogConsumer::subscribe(.., Duration::ZERO)) and keep thestartrename. The Dart bindings were regenerated. - Removed a dead quest link:
quest/m2/README.mdno longer links to the deletedcatalog-at-timestamp.md.
I grepped the bindings, docs and interop clients for the old group names after the merge. The only hit is a historical CHANGELOG.md entry. No links point to the deleted quest files.
claude-opus-5-5 | 𝕏
…ing/bindings Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
✅ No new issues found. The third merge of
mainkeeps the rename intact.
Reviewed changes
I reviewed what changed since the last Pullfrog review at fc9e888: one more merge of main, which brings in #8961 among other changes.
- Updated moq-c fill serving to
FillGroups:GroupRequestholdsArc<moq_net::track::FillGroups>and onlystart, with no leftoversequencefield.serve_fillloops onstart. - Adopted
main's one-argumentfinish_at: BothPublish::track_finish_at(moq-c) andMoqTrackProducer::finish_at(moq-ffi) now callfinish_at(Position::group(final_start)). - Updated the ffi tests to the timestamped
append_group:media_group_decodes_arrival_order_groupscallsappend_group(Timestamp::from_micros(n))and still asserts.start(). - Kept the bindings quest as a rewrite:
quest/m2/time-addressing/bindings.mdis now[M] Bindings start a group at a given timestamp. It tracks the leftover from #8961: moq-ffiappend_group()and moq-ctrack_groupshould take a required start.maindeletedgroup-api.md, so this PR no longer edits it.
I grepped rs/moq-ffi, rs/moq-c, every wrapper, doc/lib, and the interop clients for the old group names after the merge. The only hits are CHANGELOG.md history and the JS package, which is out of scope. Every other sequence in moq-ffi and moq-c belongs to a datagram.
claude-opus-5-5 | 𝕏
…ing/bindings Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
✅ No new issues found. The fourth merge of
mainleaves the rename intact.
Reviewed changes
I reviewed what changed since the last Pullfrog review at 6bcb650: one more merge of main, which brings in #8925, #8985 and #8962.
- Dropped the regenerated Dart bindings from the diff: #8925 stopped committing
dart/moq_ffi/lib/src/moq.dart. The file is now gitignored and built byjust dart generate, so it comes from the renamed moq-ffi and matches the hand-written Dart wrapper and tests, which callstart().
I grepped the bindings, doc/lib and the interop clients for the old group names again. Every remaining sequence belongs to a datagram (MoqDatagram, Dart Datagram, Python _records.Datagram, the moq-c datagram struct), apart from the out-of-scope JS and Rust interop clients.
claude-opus-5-5 | 𝕏

Finishes quest/m2/time-addressing/bindings.md: every binding names a group's start
start, notsequence, mirroring Rust'sgroup::Info. The quest is rewritten to the one item left, a requiredTimestampstart onappend_group()andtrack_group(see Decisions); the other quests' mentions of the rename now read as done.Summary
MoqGroupConsumer/MoqGroupProducer/MoqMediaGroupConsumer::sequence()isstart();MoqMediaGroupConfig.sequenceisstart;fetch_group, the media and containerseek,MoqTrackProducer::{create_group, finish_at}andMoqFill::{accept, is_wanted, unwanted}takestart(final_startforfinish_at); docs say "start order" and "ordered cursor" for what they called "sequence order" and "sequence cursor".moq_group_request_sequenceismoq_group_request_start,moq_publish_group_sequenceismoq_publish_group_start;moq_publish_media_seek,moq_publish_container_seek,moq_publish_track_group_at,moq_publish_track_finish_atname their argumentstart(ABI unchanged for those).group.start,Start(),.start,start()); the checked-in Dart bindings are regenerated withjust dart generate.doc/libpages (C, Dart, layers, index) andtest/interop/clients/python/sockets.pyuse the new names.sequence(the datagram track's counter, not a group), and the JS package (its own quest, js.md).Impact
Public API: breaking in every binding. Wire: none.
Migration (for each package's
MIGRATE.mdat the release cut):sequencetostarteverywhere it names a group:MoqGroupConsumer.sequence(),MoqGroupProducer.sequence(),MoqMediaGroupConsumer.sequence()becomestart(); thesequenceargument offetch_group,seek,create_group,accept,is_wanted, andunwantedisstart;finish_at(final_sequence)isfinish_at(final_start);MoqMediaGroupConfig.sequenceisstart. Keyword and labeled-argument callers (Python, Swift, Dart) must rename the argument too.group.sequenceisgroup.start;create_group(sequence),finish_at(final_sequence),seek(sequence),fetch_group(name, sequence),Fill.accept/is_wanted/unwanted(sequence)takestart.Sequence()onGroupConsumer,GroupProducer, andmedia.GroupConsumerisStart();media.GroupConfig.SequenceisStart.group.sequenceisgroup.start;createGroup(sequence:),accept(sequence:),isWanted(sequence:),unwanted(sequence:),fetchGroup(name:sequence:)arestart:;finish(at finalSequence:)isfinish(at finalStart:).sequence()isstart(), thesequenceparameter isstart(finalSequenceisfinalStart).moq-c, shipping as libmoq): callmoq_group_request_startandmoq_publish_group_startinstead of the_sequencefunctions; nothing else changes in the ABI.Models
Size: S
Implementer: Claude Code, claude-sonnet-5-5, high effort (iterate, S, arm B)
Validation
just test interop --all: all checks passed, including the Python, Go, and C clients against Rust and the JS clients.just check(rs, c, cpp, py, go, dart, js, kt/swift format-level checks, quest): passes, nextest included (moq-ffi,moq-c).start()/start) the other UniFFI languages already compile.just checkpasses exceptmoq-c'sserver_accepts_a_session(moq_session_close(client)returns -21), which also fails 4 of 10 runs alone on a clean checkout of main 73d65ed; feat(moq-video)!: encode::Producer takes raw frames and follows the grant #8964 already adds the quest for it.just test interop --allpasses on the head (one run failed once and passed on two reruns).cargo test -p moq-cfailsraw_track_subscription_options_and_updateon main too (checked on a clean checkout of the claim commit), but passes under nextest and alone; unrelated and left alone.Decisions
Taken without asking (the user is away), each open to review:
sequence()getter is renamedstart()as-is (nostart_timeor similar), to mirrorgroup::Info.sequencefield andmoq_datagram_*sequence outputs are a different identity and keep their name.index" has nothing to apply to: no binding exposes a frame index exceptMoqPosition.frame, which already has its own name.MIGRATE.mdfiles are not edited; the release cut writes them from the Impact section above.doc/libpage saying how to migrate" is read as: pages use the new names, and the migration note lives in Impact here (per AGENTS.md), not in a per-page callout.rs/moq-ffi/src/media.rs,producer.rs,rs/moq-c/src/publish.rs, the checked-in Dart bindings (regenerated), and quest files; main's side won, renamed tostart. feat(ffi)!: binding selectors can grow, and a null max age means unlimited #8948 and feat(net)!: writing a group needs no invented start, and its end has one word #8961 deletedffi-open-selectors.mdandgroup-api.md, so those deletions stand.start; a datagram's own counter stayssequence(MoqDatagram.sequence), so those lines are restored, as is the Python README's "out of start order".append_group()and moq-c'strack_grouptake a requiredTimestampstart, dropping bothnext_starts. It adds a parameter to the C ABI and every wrapper's call sites, tests, and docs (Swift and Kotlin cannot be built on this host); it is not the rename this PR makes. Soquest/m2/time-addressing/bindings.mdis rewritten to that item, sized M, with the maintainer's recommendation kept, instead of deleted.Settled (maintainer, 2026-11-17, when picking this PR to merge): ✅ split the required-start change on
append_group()andtrack_groupout into the rewrittenquest/m2/time-addressing/bindings.md(rejected: doing it in this PR).Follow-ups
None.
(Written by Claude Sonnet 5.5 with high effort)
Review
Rewritten by
quest reviewafter each round.Head: 4aa7694
Base: origin/main at 60dfbbf
Risk: high,
The public binding API rename can break downstream callers using the previous names, requiring caller migration or a revert to restore compatibility.Classified: medium by default
Reviewer: Codex, gpt-6.1-sol, medium effort
Session:
01a1e77e-6bc3-7b80-bd18-315c4b47a9fe, round 3Score: 10/10,
The new commits only merge base changes, with no conflicting resolutions or new actionable regressions in the branch’s rename; builds and tests were not run.Raised the risk to high:
The public binding API rename can break downstream callers using the previous names, requiring caller migration or a revert to restore compatibility.Rounds: 4; first round 0; findings 0: fixed 0, refuted 0, open 0
Findings: none
Reviewer: Codex, gpt-6.1-sol, low effort, shadow
Session:
01a1e46e-249e-7792-8710-e97fe1a3af2aRounds: 1; first round 0; findings 0: fixed 0, refuted 0, open 0