Skip to content

quest: hard-fork UniFFI, plus payload, async, and BoltFFI spikes - #5498

Merged
kixelated merged 5 commits into
mainfrom
quest/uniffi-fork-plan
Oct 14, 2026
Merged

kixelated merged 5 commits into
mainfrom
quest/uniffi-fork-plan

Conversation

@kixelated

@kixelated kixelated commented Oct 14, 2026 •

Copy link
Copy Markdown
Collaborator

Problem

UniFFI drives every non-Rust binding, and it costs us in three ways.

Separately, moq-ffi's async layer (ffi::Task: a tokio Mutex, watch, select, and spawned work) sits on top of a poll-based moq-net without using kio.

Approach

Six new quests plus edits to existing ones. No code.

m1

  • quest/m1/boltffi.md [M]: a parallel spike, BoltFFI vs UniFFI on a slice of moq-ffi in Python, Kotlin, and Swift, with its own benchmarks, a size table, and the cost of carrying each one. It picks which one the fork starts from.
  • quest/m1/uniffi-fork.md [L]: requires the spike. A hard fork in a fresh moq-dev repo (written for UniFFI, re-planned if BoltFFI wins).
    • Holds UniFFI's core and every generator, with one lockfile and one tag.
    • Publishes renamed crates to crates.io, so moq reads one pin.
    • The three kixelated/uniffi-* forks are archived.
  • quest/m1/ffi-bytes.md [L]: a payload benchmark in all six wrappers, run nightly, which becomes the shared harness.
    • The fork lifts and lowers Vec<u8> with one memcpy. The serialized format is unchanged.
    • &[u8] arguments only if the numbers justify fixing the Go and C++ forks and Dart's leak.
  • quest/m1/ffi-poll.md [M]: a spike comparing kio poll-native exports and a foreign poll(waker) against ffi::Task, in Python and Go.

m2

Edits

Decisions

Generator spike scope

kio goal

  • Poll-native exports
  • Internal swap only
  • Expose poll to foreign
  • ✅ (maintainer) Explore both poll-native exports (possibly better perf) and exposing poll to foreign

u8 scope

  • ✅ Arguments plus an upstream waiter (later reshaped, below)
  • Arguments only
  • Arguments plus returns in a fork

Milestones

  • ✅ u8 and kio in m1, the spike in m2
  • All m2
  • All m1

Spike candidates

  • ✅ BoltFFI only. Diplomat has no async, Swift, Go, or data enums, and its JS breaks on crates that use wasm-bindgen.
  • BoltFFI + Diplomat
  • BoltFFI + Diplomat for C++ only

Relationship to #5478

kio split

  • ✅ One m1 spike covering both shapes
  • Two quests
  • One m1 implementation

u8 benchmarks

  • ✅ Every wrapper
  • Python + Go + Kotlin
  • Python only

u8 reshape (after finding that &[u8] is sync-arguments-only and that the forks break on it)

  • ✅ Benchmark, then a bulk memcpy, then &[u8] only if justified
  • &[u8] plus reshaping the records
  • Bulk copy only

BoltFFI slice

  • ✅ Python + Kotlin + Swift, hot path
  • Python only
  • A full moq-ffi port

Where the #5478 edit goes

Until upstream ships the bulk copy

  • Wait, no patch
  • ✅ Carry a [patch] until release. Superseded by the hard fork.
  • Work around it in moq-ffi

Fork repo shape

  • One workspace, one tag
  • One repo, separate tags
  • Generators only
  • ✅ (maintainer) moq-dev/uniffi holds the generators plus the core

Fork rank

  • ✅ m1, before u8
  • m1, independent
  • m2

Repo base

  • A GitHub fork with generator directories
  • ✅ (maintainer) A fresh repo, no submodules, hard fork
  • Generators only, plus a patch crate

Divergence

  • Upstream-first and wire-compatible
  • ✅ Free to diverge
  • Upstream-first, may diverge

Publishing

  • ✅ Publish renamed crates
  • Keep [patch] and stay compatible
  • Stop publishing moq-ffi

Zero-copy returns

  • ✅ A fork quest in m2
  • Keep the upstream waiter
  • Drop it

Namespaces

  • ✅ Yes, an m2 fork quest
  • m1
  • Not now

BoltFFI as the base (maintainer, after the PR opened)

  • ✅ Spike BoltFFI in parallel: it's not clear whether BoltFFI or UniFFI is the better starting point. The spike moves to m1 with no harness dependency, and the fork Requires it.

Impact

Quest files only. Public API: none. Wire: none. quest check passes.

(Written by Claude Opus 5.5)

🤖 Generated with Claude Code


View with [code]smith Autofix with [code]smith
Need help on this PR? Tag @codesmith-bot with what you need.

@coderabbitai

coderabbitai Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 14 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 4 included reviews currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration
  • Configuration used: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: eb89869d-9949-4dba-b3e0-2fdaf3b743eb
📥 Commits

Reviewing files that changed from the base of the PR and between f9c2c9f and 63fd576.

📒 Files selected for processing: 10
  • quest/m1/README.md
  • quest/m1/boltffi.md
  • quest/m1/ffi-bytes.md
  • quest/m1/ffi-poll.md
  • quest/m1/ffi-shape/README.md
  • quest/m1/uniffi-fork.md
  • quest/m2/README.md
  • quest/m2/ffi-bytes-return.md
  • quest/m2/ffi-size-profile.md
  • quest/m2/uniffi-namespaces.md
  • 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

Comment @coderabbitai help to get the list of available commands.

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 14, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-14T03:45:45.918654Z f0060d1 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector 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.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f0060d1263

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread quest/m1/ffi-bytes.md Outdated
Comment on lines +29 to +30
`memcpy` in [moq-dev/uniffi](/quest/m1/uniffi-fork.md). The serialized
format is unchanged, so no generator or binding API changes.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Do not count the memcpy as a one-copy path

For record fields and returned values such as MoqFrame.payload, retaining UniFFI's serialized format still requires the wrapper to copy between its native byte container and RustBuffer, followed by the core copy between RustBuffer and Vec<u8>. Replacing the element loop with memcpy only accelerates one of those copies; it cannot satisfy the stated one-copy goal without the ownership/ABI work deferred to ffi-bytes-return. Either narrow this quest's acceptance criterion to eliminating per-byte overhead or include the second-copy elimination here.

Useful? React with 👍 / 👎.

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.

Agreed. The goal now requires no per-byte copies and has the report count the bulk copies. It also notes that records and returns keep two copies until zero-copy returns lands.

(Written by Claude Opus 5.5)

Comment thread quest/m1/ffi-poll.md Outdated
cancel bugs (#2932, the swallowed-event fix) came from that machinery.
- **Shape A, poll-native exports**: an async export is a `kio::wait` over the
underlying `poll_*`, and UniFFI's `RustFuture` polls it directly. No
per-handle mutex and no spawned task. Cancelling the foreign future drops

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Model UniFFI cancellation before dropping Task machinery

With the UniFFI behavior this fork starts from, foreign cancellation only stops polling and the Rust future is retained until rust_future_free; rs/moq-ffi/src/ffi.rs:324-326 and its cancellation regressions explicitly depend on that behavior, which is also the subject of upstream issue #2771. Therefore Shape A does not automatically drop the waiter or release a held handle mutex when the host cancels. Make the fork-level cancel/drop change a required part of Shape A rather than assuming it in the baseline comparison.

Useful? React with 👍 / 👎.

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.

Agreed. Shape A now states that UniFFI keeps the future until rust_future_free (#2771). It includes the core change that drops the future on cancel, prototyped on a branch if the fork doesn't exist yet, and measures with and without it.

(Written by Claude Opus 5.5)

Comment thread quest/m2/boltffi.md Outdated
Comment on lines +22 to +24
sync-only, and async constructors and static async methods are dropped
(boltffi/boltffi#95, which `connect` hits). One maintainer wrote about 80%
of the code. Same-name types in one target probably collide (RFC #700).

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Do not classify connect as an unsupported async static

MoqClient::connect is an async instance method taking &self at rs/moq-ffi/src/session.rs:575, while BoltFFI #95 says instance async methods work and only methods without a receiver are omitted. Claiming that connect hits this gap can cause the spike to skip or misreport a required part of its comparison slice; remove that example or identify an actual static async entry point.

Useful? React with 👍 / 👎.

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.

Correct, connect takes &self. The example is now MoqMediaCatalogConsumer::subscribe, an async #[uniffi::constructor] (rs/moq-ffi/src/media.rs:1212).

(Written by Claude Opus 5.5)

kixelated and others added 4 commits October 13, 2026 20:49
…I spikes

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>
…I statics

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated
kixelated force-pushed the quest/uniffi-fork-plan branch from 39e3d32 to c83c59d Compare October 14, 2026 03:49
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated

Copy link
Copy Markdown
Collaborator Author

Merge summary. These are quest files only, with no API or wire impact.

  • New m1 quests:
    • BoltFFI-or-UniFFI spike: runs in parallel and picks the fork's base.
    • Hard fork of the binding generator: requires the spike.
    • Payload bytes: a nightly benchmark in every wrapper, plus bulk copies in the fork.
    • Poll-native async spike.
  • New m2 quests:
  • Edits to existing quests:
    • The FFI-shape revisit condition now points at the namespaces quest.
    • The size-profile quest now requires the payload harness.
  • Review fixes (Codex):
    • Payloads: the goal is no per-byte copies; records and returns keep two bulk copies until zero-copy returns lands.
    • Shape A of the poll spike now includes the core change that drops the future on cancel.
    • BoltFFI's dropped-async example is now the subscribe constructor, not connect.
    • The size table toggles default features on native only.
  • Coordination: the BoltFFI spike's slice crate also builds for wasm32, for quest(m2): spike UniFFI-generated browser bindings before growing moq-wasm #5478's browser comparison.

All decisions are in the PR body.

(Written by Claude Opus 5.5)

@kixelated
kixelated enabled auto-merge October 14, 2026 03:50

@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: 63fd576

One P3 baseline correction below. Overall direction is coherent: benchmark the candidate bases before choosing the fork, retain explicit ownership/cancellation checks, and gate further copy-elimination work on measured cost. The dependency graph is acyclic.

The independent findings are substantively addressed: copy-count goal is narrowed to bulk-copy overhead; cancel/drop semantics are now an explicit Shape A experiment; connect classification now uses an actual async constructor example. Small remaining consistency fix: quest/m1/README.md:129 still says “one bulk copy”; align it with the revised payload goal.

Limits: static GitHub review of the ten changed plans and relevant checked-in wrappers, FFI/runtime and kio paths. No tests or benchmarks run. External generator/version claims were not independently verified outside moq-dev/moq.

Comment thread quest/m1/ffi-poll.md

Decided with the maintainer on 2026-10-13:

- **Why**: moq-net is poll-based through kio, but moq-ffi does not use kio.

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.

[P3] Describe the existing hot path accurately

moq-ffi already uses kio::wait in the chosen track-consumer hot path (rs/moq-ffi/src/consumer.rs:369–387), and Task::run already polls in place rather than spawning that call (ffi.rs:319–348). Describing the baseline as not using kio/detached work obscures what Shape A actually removes. Update this paragraph to distinguish run from detached and frame the comparison around the remaining synchronization, cancellation and shutdown costs, preserving the existing read-lane semantics.

@kixelated
kixelated added this pull request to the merge queue Oct 14, 2026
Merged via the queue into main with commit 071c6f8 Oct 14, 2026
4 checks passed
@kixelated
kixelated deleted the quest/uniffi-fork-plan branch October 14, 2026 03:58
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.

Library mode: a type cannot reference an external type with the same name

1 participant