Skip to content

feat(ffi): bump the exporter's moq pin to 1aa86d5e6 - #881

Merged
kixelated merged 5 commits into
mainfrom
quest/m1/ffi-refusals/moq-pin
Nov 19, 2026
Merged

kixelated merged 5 commits into
mainfrom
quest/m1/ffi-refusals/moq-pin

Conversation

@kixelated

@kixelated kixelated commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

Bumps the exporter's moq pin (moq_rev in ffi/justfile) from ffcb7cd9 to moq's current main, 1aa86d5e6, and ports every moq program and bench to its API. Completes and deletes quest/m1/ffi-refusals/moq-pin.md.

Why now

The quest waited on moq-tokio and the moq-ffi facade building without tripping recursion_depth_exceeding_limit. moq-dev/moq#9143 fixed the session driver's Send and Sync proofs. At 1aa86d5e6, just ffi moq-cpp builds both under -D recursion_depth_exceeding_limit with no overflow, so the wait has cleared.

Changes

  • Excludes (ffi/moq/ffi.toml):
    • Dropped 17 stale excludes: bytes, kio, hang::moq_net, moq-quic's and moq-tokio's quic::driver items, mp4_atom's two, the rustls ConfigBuilder pair, Request::within, websocket::Listener::accept, and the 18 container::Producer::modify instances, which export as exclusive lends now that Guard is reachable.
    • Excluded the 5 refusals moq's main adds, as the quest's Waiting item planned: escape and unescape (Cow<'_, str>), Mpegts::deserialize (serde's generic Deserializer), and server::Streams::{tcp, unix} (Options of std listeners, not Clone).
    • ffi/moq/web.toml keeps the three of them outside moq-tokio.
  • Test programs (ffi/moq/moq.{c,cpp,kt,py,swift,go,dart}), ported to moq's API:
    • Groups are keyed by a start Timestamp: append_group(start), and write_frame takes a non-optional Timestamp. On an untimed track that is Timestamp::unscaled(key).
    • origin::Producer::route(path, RouteOptions) replaces create_broadcast and announce(Route::default()).
    • Ranges are inclusive Anchor::Time ranges; Range::groups and Anchor::Absolute are gone.
    • group::Producer::finish returns a Finished handle.
    • Timestamp::now is gone.
  • Bench programs (ffi/moq/bench/export.*):
    • Each group starts at its first frame's time from one running microsecond counter, as moq's own moq-ffi/src/bench.rs does.
    • The cases that reused one timestamp now take one per group.
    • The getter reads group::Demand::start instead of the removed sequence.
  • moq-c.c: moq renamed rs/moq-c to rs/libmoq (moq-dev/moq#8941). bench-build now builds --package libmoq, and moq-c.c uses moq_origin_route, moq_route_broadcast, and the timestamped moq_publish_track_group.
  • Docs:
    • ffi/README.md no longer gives Timestamp as its opaque-value example (see the follow-up).
    • The bench README and report.py name the getter demand.start(). The README's present-tense claims say Timestamp is a handle at this pin and was a value at ffcb7cd9, and its write row takes one timestamp per group.
    • The test programs' comments say a timestamp is a lent handle, and flake.nix names rs/libmoq.
  • Quests:
    • This quest is deleted, with its Required link in no-config and its links in the TS pin quest and the refusals epic.
    • no-config now lists the 6 refusals the census still reports at the pin.

Census

just ffi census at 1aa86d5e6 passes. It reports:

  • 567 types, all exported, so no type is refused.
  • 2 refused functions: escape and unescape.
  • 4 refused methods and fields: Mpegts::deserialize, Streams::{tcp, unix}, and DangerousClientConfig::cfg.
  • No whole-crate re-export refusal and no unreachable-type refusal, which is the quest's Goal.

At ffcb7cd9, the last measured nightly (2026-11-11) refused 94 items and 5 types. Those had already shrunk on main before this PR, through the epic's children.

Validation

  • just ffi moq at the pin: passes. C, C++, Kotlin, Python, Swift, Go, and Dart all print ok, and mypy and pyright report 0 errors on the generated Python.
  • just ffi moq-cpp against a fresh clone of moq main (1aa86d5e6): passes, with no recursion_depth_exceeding_limit.
  • just ffi census: passes. It first caught the stale websocket::Listener::accept exclude, now dropped.
  • Bench:
    • nix develop .#bench --command just ffi bench-build builds every bench program against the real CodSpeed hooks.
    • just ffi bench-run 1 ran every program to completion, so no group start trips moq's strictly-increasing rule. The browsers did not run locally.
  • just ffi moq-web: exports and builds the wasm32 stand-in, and just ffi ts-program type-checks export.ts.
  • just ci: passes, including just ffi moq-c at the pin.
  • Second, independent check: the C, Kotlin, Python, Swift, and Go bench ports were each also linked against a no-op CodSpeed stub and run in both modes (measured and unmeasured).

Decisions

I could not prompt the maintainer, so I took my recommendation on each of these. They are listed for review:

  1. Pin to moq's current main (1aa86d5e6). The quest's Goal and the 2026-11-09 decision both say current main.
  2. Exclude the 5 new refusals rather than add rules for them here. The quest's Waiting item planned this ("the bump fixes in ffi/moq/ffi.toml"), and the epic leaves each remaining refusal to no-config, which now lists them.
  3. Bench timestamps: one per group, each group starting at its first frame's time. Strictly increasing group starts are now required, and this keeps each case's per-frame cost unchanged. It mirrors moq's own bench.
  4. The dial check is replaced, not dropped. auth::Tokens::dial / auth::Dial became pub(crate) in moq-net.
    • Kotlin and C, which had no Client URL getter path in their tests, drop that check.
    • Python, Swift, Go, and Dart check the same URL round trip through Client::with_url(..).url().
  5. Keep the bench language label moq-c after moq's rename to libmoq. That keeps the CodSpeed case names and the README tables continuous. Only the package name in bench-build changes.
  6. Accept Timestamp becoming a handle at this pin, and fix it in a follow-up.
    • moq's Timestamp gained scale: Option<Timescale> for unscaled group keys, so the exporter's layout model now treats None as possibly uninitialized, and Timestamp crosses as a handle rather than as its 16 bytes.
    • It costs 35 ns a stamped frame in C in this PR's one-round bench (208 vs 173 ns).
    • Fixing it changes the exporter's layout rule, which is outside a pin bump.
  7. Keep the niche-values follow-up as a general rule (maintainer decision, comment). Its Plan now says it covers every Copy type with a niche-encoded enum field, not moq specifically.
  8. The claim's leftover local branch was left alone. It held feat(ffi): export a type the root does not reach by its public path in its crate #721's already-landed work, and a stale worktree from 2026-11-12 had it checked out. This work was built on the claim commit from a differently named local branch and pushed to the quest's branch.

Public API

  • rust2-ffi's command line and rules are unchanged.
  • The generated moq bindings follow moq's API at the new pin (moq's breaking changes, listed above).
  • In every binding, Timestamp changes from an opaque value to a handle, until the follow-up lands.

Follow-ups

  • Niche values [M]: cross a Copy type whose niche fills its bytes, such as Option<NonZero<u64>>, as an opaque value, so moq's Timestamp is a 16-byte value again. A child of the exporter epic, since it changes generated APIs, and required by ship. Kept by the maintainer as a general rule for niche-encoded enum fields, not moq-specific; no open decisions.

Models

Size: S
Implementer: Claude, claude-opus-5-5, unknown effort (arm A)
Implementer: Claude Code, claude-opus-5-5, unknown effort (iterate, S)

(Written by Claude Opus 5.5)

Review

Rewritten by quest review after each round.

  • Head: 1d90c85

  • Base: origin/main at 46c5863

  • Risk: medium, the base has no RISK.md to name what is always high or customer-facing, so every change is medium

  • Classified: medium by default

  • Reviewer: Codex, gpt-6.1-sol, medium effort

  • Session: 01a1f385-e902-7070-aac9-d28b10971443, round 2

  • Score: 10/10, The incremental changes clarify documentation, comments, and assertion messages without changing behavior; no actionable findings remain from code inspection.

  • Rounds: 3; first round 1 (medium 1); findings 1 (medium 1): fixed 1, refuted 0, open 0

  • Findings: none

  • Reviewer: Codex, gpt-6.1-sol, low effort, shadow

  • Session: 01a1f548-787e-75c2-ac4f-4b85e4ff5ab4, round 1

  • Score: 8/10, The scoped diff consistently updates the moq pin, exclusions, examples, and benchmarks for the upstream API changes, with no actionable defects found by inspection, though builds and tests remain unverified.

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

  • Findings: none

Summary by CodeRabbit

  • New Features
    • FFI benchmarks now use explicit timestamps for track groups and frames across language bindings.
    • Timestamp and group completion handling is updated in benchmark and FFI examples.
  • Bug Fixes
    • Updated getter benchmarks to measure group start timestamps.
    • Expanded FFI checks for timestamped and untimed writes, time-based subscription ranges, and routed broadcasts.
  • Documentation
    • Updated benchmark descriptions and FFI guidance to reflect current behavior.

Summary by CodeRabbit

  • Documentation
    • Updated FFI benchmark guidance to reflect timestamped group and frame writes, and revised the examples for time-based range queries.
    • Added a proposal describing how certain value types may be represented across FFI bindings.
  • Tests
    • Updated cross-language FFI checks and benchmarks for explicit timestamps, routed publications, and revised demand getters.

@coderabbitai

coderabbitai Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The PR updates the pinned moq revision and FFI export configuration. Binding examples and benchmarks now use explicit group timestamps, with benchmark cases measuring demand.start(). The PR also updates range, snapshot, routing, and client URL examples, plus related quest notes.

Changes: MoQ FFI alignment

Layer / File(s) Summary
Pin, export configuration, and quest records
ffi/justfile, ffi/moq/ffi.toml, ffi/moq/web.toml, ffi/README.md, quest/m1/ffi-export/*, quest/m1/ffi-refusals/*, quest/m2/ts-model/moq-pin.md, flake.nix
The moq revision and FFI exclusion lists change. FFI mapping notes and quest documents record niche-value work, refusal counts, and the pinned revision. The benchmark environment comment identifies rs/libmoq.
Binding examples for timestamped groups and routes
ffi/moq/moq.c, ffi/moq/moq.cpp, ffi/moq/moq.dart, ffi/moq/moq.go, ffi/moq/moq.kt, ffi/moq/moq.py, ffi/moq/moq.swift
The binding examples pass explicit timestamps to groups and frames and create broadcasts through routes. They update subscription ranges to use time anchors and use fixed timestamps for snapshot updates. Client URL checks use configured client URLs; some token-based dial tests are removed.
Timestamped cross-language benchmarks
ffi/moq/bench/export.*, ffi/moq/bench/moq-c.c, ffi/justfile, bench/ffi/README.md, bench/ffi/report.py
Benchmark cases assign increasing microsecond timestamps to groups and use group timestamps for frames where applicable. The getter case measures demand.start(). The C benchmark build targets libmoq, and benchmark documentation describes the updated cases.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Other

Possibly related PRs

  • kixel-ai/rust2#742: Defines how eligible exported Rust Copy types cross by value or as handles, which relates to the Timestamp handle-or-value behavior described here.
Merge Risk: Minimal · up to 1d90c

This PR bumps the moq pin and updates the FFI examples, benchmarks, and docs to the new timestamped API. No concrete merge-blocking risk was found.

Architecture risk: Low · up to 1d90c

The change affects 4 systems.

Changed systems: ffi, quest, bench, flake.nix

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

  • observed — ffi (service) was modified; 21 changed files map to changed impact.
  • observed — quest (service) was modified; 6 changed files map to changed impact.
  • observed — bench (service) was modified; 2 changed files map to changed impact.
  • observed — flake.nix (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

  • observed — Modified behavior in bench/ffi/report.py: The getter case now benchmarks demand.start() instead of demand.sequence(); the description remains a u64 getter.
  • observed — Modified behavior in ffi/README.md: The Rust-to-C mapping rule removes Timestamp from its examples of Copy and Send types represented as opaque values; stats::Traffic remains the example. The mapping behavior described by the row is otherwise unchanged.
  • observed — Modified behavior in ffi/justfile: The default moq revision changes from ffcb7cd9748422daa30e935ec464108b5a8ebb71 to 1aa86d5e6d091848cb1848c702a911099706b1a4.
  • observed — Modified behavior in ffi/justfile: The benchmark description changes the C program’s source from moq’s hand-written rs/moq-c to rs/libmoq.
Pre-merge checks: Passed 4

Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title names the main change: bumping the exporter's moq pin to revision 1aa86d5e6 in the FFI. The raw summary and PR objectives confirm that ffi/justfile moves moq_rev from ffcb7cd9 to 1aa86d5e6, …
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: bumping the exporter's moq pin to revision 1aa86d5e6 in the FFI. The raw summary and PR objectives confirm that ffi/justfile moves moq_rev from ffcb7cd9 to 1aa86d5e6, and that the examples and benchmarks were ported to the upstream API. The title is concise and specific, and it omits the API port, which is expected.

Finishing Touches

Generate unit tests (beta)

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

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: e60a8132-8102-4628-9107-564edf8a95e3
Commits

Reviewing files that changed from the base of the PR and between c4fa97e and 1d90c85.

Files selected for processing: 8

  • bench/ffi/README.md
  • ffi/moq/moq.dart
  • ffi/moq/moq.go
  • ffi/moq/moq.kt
  • ffi/moq/moq.py
  • ffi/moq/moq.swift
  • flake.nix
  • quest/m1/ffi-export/niche-values.md
Files skipped from review as they are similar to previous changes: 7

  • bench/ffi/README.md
  • ffi/moq/moq.dart
  • ffi/moq/moq.go
  • ffi/moq/moq.kt
  • ffi/moq/moq.py
  • ffi/moq/moq.swift
  • quest/m1/ffi-export/niche-values.md

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

kixelated and others added 2 commits November 19, 2026 02:35
moq's main now builds moq-tokio and the facade without tripping
recursion_depth_exceeding_limit (moq-dev/moq#9143). Port every moq
program and bench to its API: groups keyed by a start timestamp,
origin routes in place of publications, inclusive time ranges, and
libmoq in place of moq-c. Drop the stale excludes and exclude the six
new refusals.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated kixelated changed the title Bump the exporter's moq pin past its re-export and reachability fixes feat(ffi): bump the exporter's moq pin to 1aa86d5e6 Nov 19, 2026
…otlin and Dart

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated
kixelated marked this pull request as ready for review November 19, 2026 11:21

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

ℹ️ No blocking issues. Some comments and docs still say Timestamp crosses as a Copy value, which this pin changes.

Approach: Sound. It bumps the pin, ports each program to moq's new API, and turns stale excludes into the five new ones the census reports. The Timestamp layout regression is left to a planned follow-up rather than mixed into the bump.

Reviewed changes

I read all 29 files. I also checked the Go receiver-move semantics and the group-start ordering in every bench program.

  • Pin and excludes: moq_rev moves to 1aa86d5e6. ffi.toml drops 17 stale excludes and adds escape, unescape, Mpegts::deserialize, and Streams::{tcp, unix}. web.toml keeps the three of those that are not in moq-tokio.
  • Test programs: All 7 languages are ported:
    • append_group(start) and a non-optional write_frame timestamp (Timestamp::unscaled(0) on untimed tracks).
    • finish now returns Finished.
    • route(path, RouteOptions) replaces create_broadcast.
    • Ranges use Anchor::Time.
    • The dial check moves to Client::with_url.
  • Bench programs: Every case takes its group starts from one running microsecond counter, so starts strictly increase across cases. That includes Swift's writer task, which reserves its range up front, and the throughput helpers, which thread the counter through. Go's Finish moves the receiver (self.Handle_.Moved() in ffi/src/go.rs), so dropping group.Close() there is correct.
  • moq-c.c and bench-build: They follow moq's rs/moq-c → rs/libmoq rename and the timestamped moq_publish_track_group.
  • Quests: moq-pin.md is deleted and its links are cleaned up. niche-values.md is added under ship to restore Timestamp as an opaque value.

ℹ️ bench/ffi/README.md still says Timestamp crosses as a value

The PR updates ffi/README.md so it no longer gives Timestamp as its opaque-value example. But the bench README still says, in the present tense, that Timestamp crosses as its 16 bytes. Until the niche-values follow-up lands, that contradicts what the binding generates at this pin. Its case table also still describes write as using one Timestamp, but every case now converts one per group.

Technical details
# Bench README describes Timestamp as a by-value Copy type at a pin where it is a handle

## Affected sites
- bench/ffi/README.md:35 — `write` row: "with one `Timestamp`"; each group now takes its own start, converted once per group
- bench/ffi/README.md:454-455 — "`Timestamp` is `Copy` with private fields, so it crosses as its 16 bytes, and a stamped frame allocates and frees nothing in Rust"
- bench/ffi/README.md:581 — "A `Copy` type with private fields, such as `Timestamp`, crosses by value"
- flake.nix:310 — comment still says `rs/moq-c` (renamed to `rs/libmoq`)

## Required outcome
- Present-tense claims match the binding at moq `1aa86d5e6`, where `Timestamp` is a handle until quest/m1/ffi-export/niche-values.md lands. Dated measurement sections can stay as they are but should say they were taken at `ffcb7cd9`.
- The `write` row describes one timestamp per group.

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

Comment thread ffi/moq/moq.kt Resolved
@codspeed

codspeed Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

Merging this PR will degrade performance by 5.39%

2 warnings

⚠️ 36 benchmarks are dominated by system calls

System calls cannot be simulated consistently and are left out of the measure. The reported value understates the real cost. Switch to the Walltime instrument to measure them.

Learn more about system calls

See affected benchmarks

⚠️ 8 benchmarks with a significant change ran on different hardware

Their base and head results were measured on machines with a different CPU, core count or memory, so the changes might not come from the code. Run base and head on the same runner type.

Learn more about Macro Runners

See affected benchmarks

⚡ 3 improved benchmarks
❌ 5 regressed benchmarks
✅ 75 untouched benchmarks

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

Benchmark BASE HEAD Efficiency
❌ stamped 1.6 s 2.3 s -29.53%
❌ stamped 170.9 ms 214 ms -20.13%
❌ ready 5.6 s 6.8 s -16.7%
❌ stamped 170.8 ms 203.1 ms -15.93%
❌ stamped 53.7 ms 61.5 ms -12.7%
⚡ record 21.9 ms 16.7 ms +31.64%
⚡ loop 12.3 s 9.7 s +26.64%
⚡ woken 10.8 s 9.7 s +11.94%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.


Comparing quest/m1/ffi-refusals/moq-pin (1d90c85) with main (46c5863)

Open in CodSpeed

Fixes pullfrog's findings on #881: the Kotlin, Python, Swift, Dart, and Go
programs' comments and the bench README still called it a copied value,
and flake.nix still named rs/moq-c. Records the maintainer's answer that
niche values is a general rule, not moq-specific.

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

Copy link
Copy Markdown
Collaborator Author

Maintainer decision on this PR's follow-up, relayed from the maintainer's brief:

  • ✅ Keep quest/m1/ffi-export/niche-values.md (rejected: drop it).
  • Its Plan says it is a general rule for niche-encoded enum fields, not moq-specific. The next head records this in the quest's Plan.

(Written by Claude Opus 5.5)

@kixelated

Copy link
Copy Markdown
Collaborator Author

Answering pullfrog's review body finding: fixed in 1d90c85. bench/ffi/README.md's write row takes one Timestamp a group, and its "call per frame timestamp" and "Copy values" passages now say Timestamp was a value at moq ffcb7cd9 and is a handle at 1aa86d5e6 until the niche-values follow-up lands. flake.nix names rs/libmoq.

(Written by Claude Opus 5.5)

@kixelated

Copy link
Copy Markdown
Collaborator Author

Applies the maintainer decision at 1d90c85: quest/m1/ffi-export/niche-values.md is kept, and its Plan opens by saying it is a general rule for every Copy type with a niche-encoded enum field, not a fix for moq. The PR body's Decisions (item 7) and Follow-ups record it.

(Written by Claude Opus 5.5)

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

✅ No new issues found.

Reviewed changes

I reviewed the delta since c4fa97e, a docs and comments commit that addresses the earlier feedback.

  • Bench README: The write row now says one Timestamp a group. The present-tense claims say Timestamp was a value at ffcb7cd9 and is a handle at 1aa86d5e6 until niche-values lands.
  • Test program comments: Kotlin, Python, Swift, Dart, and Go now say a timestamp is a lent handle. The "stays usable" assertion messages match.
  • flake.nix: The comment names rs/libmoq.
  • niche-values.md: The Plan now states the rule covers every Copy type with a niche-encoded enum field.

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

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