Skip to content

feat(ffi)!: bindings address groups by start, not sequence - #8915

Merged
kixelated merged 8 commits into
mainfrom
quest/m2/time-addressing/bindings
Nov 17, 2026
Merged

kixelated merged 8 commits into
mainfrom
quest/m2/time-addressing/bindings

Conversation

@kixelated

@kixelated kixelated commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

Finishes quest/m2/time-addressing/bindings.md: every binding names a group's start start, not sequence, mirroring Rust's group::Info. The quest is rewritten to the one item left, a required Timestamp start on append_group() and track_group (see Decisions); the other quests' mentions of the rename now read as done.

Summary

  • moq-ffi: MoqGroupConsumer/MoqGroupProducer/MoqMediaGroupConsumer::sequence() is start(); MoqMediaGroupConfig.sequence is start; fetch_group, the media and container seek, MoqTrackProducer::{create_group, finish_at} and MoqFill::{accept, is_wanted, unwanted} take start (final_start for finish_at); docs say "start order" and "ordered cursor" for what they called "sequence order" and "sequence cursor".
  • moq-c: moq_group_request_sequence is moq_group_request_start, moq_publish_group_sequence is moq_publish_group_start; moq_publish_media_seek, moq_publish_container_seek, moq_publish_track_group_at, moq_publish_track_finish_at name their argument start (ABI unchanged for those).
  • Python, Go, Swift, Kotlin, Dart, C++: wrappers, tests, benches, and READMEs follow (group.start, Start(), .start, start()); the checked-in Dart bindings are regenerated with just dart generate.
  • doc/lib pages (C, Dart, layers, index) and test/interop/clients/python/sockets.py use the new names.
  • Left alone on purpose: a datagram's own 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.md at the release cut):

  • moq-ffi (UniFFI): rename sequence to start everywhere it names a group: MoqGroupConsumer.sequence(), MoqGroupProducer.sequence(), MoqMediaGroupConsumer.sequence() become start(); the sequence argument of fetch_group, seek, create_group, accept, is_wanted, and unwanted is start; finish_at(final_sequence) is finish_at(final_start); MoqMediaGroupConfig.sequence is start. Keyword and labeled-argument callers (Python, Swift, Dart) must rename the argument too.
  • Python: group.sequence is group.start; create_group(sequence), finish_at(final_sequence), seek(sequence), fetch_group(name, sequence), Fill.accept/is_wanted/unwanted(sequence) take start.
  • Go: Sequence() on GroupConsumer, GroupProducer, and media.GroupConsumer is Start(); media.GroupConfig.Sequence is Start.
  • Swift: group.sequence is group.start; createGroup(sequence:), accept(sequence:), isWanted(sequence:), unwanted(sequence:), fetchGroup(name:sequence:) are start:; finish(at finalSequence:) is finish(at finalStart:).
  • Kotlin and Dart: sequence() is start(), the sequence parameter is start (finalSequence is finalStart).
  • C (moq-c, shipping as libmoq): call moq_group_request_start and moq_publish_group_start instead of the _sequence functions; 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).
  • Not exercised: Swift and Kotlin builds (no toolchain on this host); their wrapper edits are mechanical against the generated names (start() / start) the other UniFFI languages already compile.
  • On the merge with main, just check passes except moq-c's server_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 --all passes on the head (one run failed once and passed on two reruns).
  • A plain cargo test -p moq-c fails raw_track_subscription_options_and_update on 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:

Settled (maintainer, 2026-11-17, when picking this PR to merge): ✅ split the required-start change on append_group() and track_group out into the rewritten quest/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 review after 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 3

  • Score: 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-e97fe1a3af2a

  • Rounds: 1; first round 0; findings 0: fixed 0, refuted 0, open 0

kixelated and others added 3 commits November 16, 2026 04:19
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>
@kixelated kixelated changed the title Bindings address groups by start feat(ffi)!: bindings address groups by start, not sequence Nov 16, 2026
@kixelated
kixelated marked this pull request as ready for review November 16, 2026 12:57
@coderabbitai

coderabbitai Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The 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: Minimal · up to 4aa76

This renames group-addressing APIs from sequence to start across the C, Rust, and language bindings. It is an intentional breaking public API change with no wire-format change, and no concrete defects were found. Swift and Kotlin builds were not exercised, so callers there should verify when they migrate.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title names the main change: the FFI bindings now address groups by start instead of sequence. The raw summary confirms renames of sequence to start across moq-ffi, moq-c, and the language wrapper…
Description check Passed The description relates directly to the changeset. It explains the sequence-to-start rename across moq-ffi, moq-c, and the Python, Go, Swift, Kotlin, Dart, and C++ bindings, lists migration notes, and…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Title check

Explanation

The title names the main change: the FFI bindings now address groups by start instead of sequence. The raw summary confirms renames of sequence to start across moq-ffi, moq-c, and the language wrappers, with the breaking-change marker matching the described public API break. The title is specific and concise.

Full details: Description check

Explanation

The description relates directly to the changeset. It explains the sequence-to-start rename across moq-ffi, moq-c, and the Python, Go, Swift, Kotlin, Dart, and C++ bindings, lists migration notes, and describes validation and the deferred Timestamp change. The described files match the raw summary.

Finishing Touches

Simplify code

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: f1499ac4-1122-4171-84dc-6743fd071f68
Commits

Reviewing files that changed from the base of the PR and between c53b790 and 4aa7694.

Files selected for processing: 59

  • cpp/moq/bench/main.cpp
  • dart/moq/bench/ffi.dart
  • dart/moq/lib/media.dart
  • dart/moq/lib/src/aliases.dart
  • dart/moq/test/moq_test.dart
  • doc/lib/c/index.md
  • doc/lib/dart/index.md
  • doc/lib/index.md
  • doc/lib/layers.md
  • go/wrapper/errors.go
  • go/wrapper/media/media.go
  • go/wrapper/moq_test.go
  • go/wrapper/origin.go
  • go/wrapper/publish.go
  • go/wrapper/runtime_bench_test.go
  • go/wrapper/subscribe.go
  • go/wrapper/types.go
  • kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt
  • kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Flows.kt
  • kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/media/Media.kt
  • kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt
  • kt/moq/src/jvmTest/kotlin/dev/moq/FfiBench.kt
  • py/moq-rs/README.md
  • py/moq-rs/benches/ffi.py
  • py/moq-rs/moq/media.py
  • py/moq-rs/moq/origin.py
  • py/moq-rs/moq/publish.py
  • py/moq-rs/moq/subscribe.py
  • py/moq-rs/tests/test_local.py
  • py/moq-rs/tests/test_socket.py
  • py/moq-rs/tests/test_testing_clock.py
  • quest/m2/README.md
  • quest/m2/time-addressing/bindings.md
  • quest/m3/ffi-exporter.md
  • rs/moq-c/README.md
  • rs/moq-c/src/api.rs
  • rs/moq-c/src/consume.rs
  • rs/moq-c/src/publish.rs
  • rs/moq-c/src/test.rs
  • rs/moq-c/src/test/parity.rs
  • rs/moq-ffi/src/bench.rs
  • rs/moq-ffi/src/consumer.rs
  • rs/moq-ffi/src/demand.rs
  • rs/moq-ffi/src/error.rs
  • rs/moq-ffi/src/media.rs
  • rs/moq-ffi/src/origin.rs
  • rs/moq-ffi/src/producer.rs
  • rs/moq-ffi/src/socket.rs
  • rs/moq-ffi/src/test.rs
  • swift/README.md
  • swift/Sources/Moq/Aliases.swift
  • swift/Sources/Moq/Broadcast.swift
  • swift/Sources/Moq/Media.swift
  • swift/Sources/Moq/Origin.swift
  • swift/Sources/Moq/Requests.swift
  • swift/Sources/Moq/Track.swift
  • swift/Tests/MoqTests/FfiBench.swift
  • swift/Tests/MoqTests/SmokeTests.swift
  • test/interop/clients/python/sockets.py

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 3 remain after this review.

@kixelated kixelated left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ℹ️ 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 become start(). MoqMediaGroupConfig.sequence becomes start. The group-addressing arguments of fetch_group, seek, create_group, finish_at and the MoqFill methods become start (or final_start).
  • moq-c: moq_group_request_sequence becomes moq_group_request_start and moq_publish_group_sequence becomes moq_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/lib pages 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.

Pullfrog  | Fix all ➔ | Fix 👍s ➔ | View workflow run | Using claude-opus-5-5 | 𝕏

Comment thread py/moq-rs/README.md Resolved
kixelated and others added 2 commits November 16, 2026 17:59
…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>
pullfrog[bot]
pullfrog Bot previously approved these changes Nov 17, 2026

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ 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.kt say sequence again, which matches MoqDatagram.sequence.
  • Fixed the broken README sentence: py/moq-rs/README.md now reads "out of start order".
  • Resolved the merge with main: The conflicted tests in rs/moq-ffi/src/media.rs and rs/moq-ffi/src/test.rs use main's new signatures (MoqJsonSnapshotConsumer::new(.., None) and MoqMediaCatalogConsumer::subscribe(.., Duration::ZERO)) and keep the start rename. The Dart bindings were regenerated.
  • Removed a dead quest link: quest/m2/README.md no longer links to the deleted catalog-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.

Pullfrog  | View workflow run | Using claude-opus-5-5 | 𝕏

…ing/bindings

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
pullfrog[bot]
pullfrog Bot previously approved these changes Nov 17, 2026

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found. The third merge of main keeps 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: GroupRequest holds Arc<moq_net::track::FillGroups> and only start, with no leftover sequence field. serve_fill loops on start.
  • Adopted main's one-argument finish_at: Both Publish::track_finish_at (moq-c) and MoqTrackProducer::finish_at (moq-ffi) now call finish_at(Position::group(final_start)).
  • Updated the ffi tests to the timestamped append_group: media_group_decodes_arrival_order_groups calls append_group(Timestamp::from_micros(n)) and still asserts .start().
  • Kept the bindings quest as a rewrite: quest/m2/time-addressing/bindings.md is now [M] Bindings start a group at a given timestamp. It tracks the leftover from #8961: moq-ffi append_group() and moq-c track_group should take a required start. main deleted group-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.

Pullfrog  | View workflow run | Using claude-opus-5-5 | 𝕏

…ing/bindings

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found. The fourth merge of main leaves 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 by just dart generate, so it comes from the renamed moq-ffi and matches the hand-written Dart wrapper and tests, which call start().

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.

Pullfrog  | View workflow run | Using claude-opus-5-5 | 𝕏

@kixelated
kixelated added this pull request to the merge queue Nov 17, 2026
Merged via the queue into main with commit 2996e1c Nov 17, 2026
6 checks passed
@kixelated
kixelated deleted the quest/m2/time-addressing/bindings branch November 17, 2026 07:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant