Skip to content

Resolve a data stream send once its packets are sent - #1295

Merged
hiroshihorie merged 7 commits into
mainfrom
hiroshi/data-streams-polled-ack
Nov 19, 2026
Merged

hiroshihorie merged 7 commits into
mainfrom
hiroshi/data-streams-polled-ack

Conversation

@hiroshihorie

@hiroshihorie hiroshihorie commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Summary

Data streams (sendText, sendBytes, sendFile, streamText, streamBytes) on native platforms had three problems since they moved to the shared Rust core:

  • Memory. Sending a large file loaded all of it into memory. A 256 MiB file grew the app by about 826 MB. It now grows by about 43 MB.
  • Silent failures. If a packet could not be sent, the error was only logged and the call still reported success. The call now throws.
  • Finishing too early. A send reported "done" as soon as the data was queued inside the SDK, before any of it went out. It now reports "done" once the data has been handed to WebRTC, which is what the JS, Swift and Android SDKs do.

The fix is in the Rust core and shipped in livekit_ffi 0.15.0. This PR moves Flutter to that version and makes the small change needed to use it. That version also fixes a memory leak in the Dart bindings.

There is no public API change, and the web is not affected.

One thing this does not fix: a message sent right before disconnect() can still be lost on a real network. See "Not covered" below.

Details

Companion to livekit/rust-sdks#1691. The dependency moves from ^0.13.4 to ^0.15.0, which also brings livekit/rust-sdks#1636, the bindings that free native buffers.

Flutter cannot take callbacks from the Rust core's threads, so it pulls outgoing packets from a queue. That queue used to acknowledge a send the moment its packets were queued. In 0.15.0 the host acknowledges each batch itself.

  • The outgoing pump pulls a batch with nextBatch(), sends its packets, then calls ack.complete(), or ack.fail() when the send throws. The core resolves the send from that. Because the pump only pulls the next batch after that, a fast producer is now paced by the data channel.
  • Closing a stream writer after the room closed stays quiet. The core now reports that the trailer could not be sent, and closing is cleanup.

Not covered

await sendText() followed at once by disconnect() is still not reliable on a real network. A send now resolves when its packets are handed to the data channel, and disconnect() does not wait for the channel to drain. On an iPhone over Wi-Fi a 200 KB text was cut off, and arrived with a one second pause before the disconnect. The other SDKs disconnect the same way, so that is a gap of its own.

Checks

Against the published livekit_ffi 0.15.0:

  • flutter analyze clean, 596 unit tests pass.
  • e2e-flutter data stream scenarios. The macOS column is with the published package. The two iOS columns are from an earlier local build of the same Rust change:
macOS iOS simulator iPhone 17 Pro, Wi-Fi
10 data stream and core scenarios pass pass pass
256 MiB sendFile, peak RSS growth +43 MB not run not run
sendText then disconnect() arrives arrives not reliable

The 826 MB figure is the same file send on macOS with livekit_ffi 0.13.4.

The outgoing pump pulls a batch, sends its packets and then completes the
batch, or fails it when the send throws. The core resolves the send from
that outcome, so a send error reaches the caller and the pump no longer
logs and drops it.
The trailer cannot be sent on a closed room, and the core now reports
that. Closing is cleanup, so the failure is not passed on.
Text sent right before a disconnect still depends on the data channel
draining before the connection closes, which this change does not cover.
A batch now carries its packets as a field and the outcome as a separate
object to report on.
hiroshihorie added a commit to livekit/rust-sdks that referenced this pull request Nov 18, 2026
…t them (#1691)

The polled outgoing data stream adapter in `core-modules` acknowledged a
send as soon as its packets were buffered. A `send_*` or `write` call
resolved before anything reached the transport, transport errors were
lost, and nothing slowed a producer down. Flutter is the one SDK on this
adapter. It shows as unbounded memory growth on a large `sendFile` and
as send errors that never reach the caller. Swift and Android pass their
own delegate, which already resolves a send once the packets are handed
to the data channel, and this brings Flutter to the same point.

`OutgoingPacketQueue.next_packets()` is replaced by `next_batch()`,
which returns an `OutgoingPacketBatch` record: the `packets`, moved out
without a copy, and an `ack` object with `complete()` and
`fail(reason)`. The send resolves when the host completes the ack. It
fails when the ack fails, is released without an outcome, or the queue
is closed. The manager already awaits each delegate call, so at most one
batch is pending.

The queue is split into two halves. The manager holds the sending half
and the host holds `OutgoingPacketQueue`, the receiving half. Releasing
the queue then drops a batch nobody pulled, which fails its send and
lets the forwarding task finish. The sending half also watches the token
its manager cancels on drop, so the task finishes when the manager goes
away, whatever the host still holds. `outgoing.rs` gains a constructor
that takes that token. Its forwarding task is unchanged, so hosts that
pass their own delegate are not affected.

This is a breaking change for hosts on the polled adapter, so the
changeset is `livekit-ffi: major`.

### Checks

- `cargo test -p livekit-ffi --no-default-features --features
core-modules` passes, 78 tests. New `polled_*` tests cover the wait, a
failed batch, a dropped batch, a closed queue, a queue released with an
unpulled batch, a manager dropped while the host keeps the queue or a
pulled batch, and 200 repeated sends that check every ack is released.
- e2e-flutter on macOS against a local server, client-sdk-flutter with
livekit/client-sdk-flutter#1295. Run together with the uniffi-dart pin
from #1636. The table is from 37c5951, and the macOS run was repeated
on the current API with the same result:

| | published 0.13.4 | #1636 only | #1636 and this PR |
|---|---|---|---|
| 256 MiB `sendFile`, peak RSS growth | +826 MB | +147 MB | +45 MB |
| `sendText` then `disconnect()`, localhost | never arrives | never
arrives | arrives |
| other 10 data stream and core scenarios | pass | pass | pass |

The same scenarios pass on an iOS simulator and on an iPhone 17 Pro over
Wi-Fi, with one exception on the phone: `sendText` then `disconnect()`
is still not reliable there. A send now resolves when its packets are
handed to the data channel, and Flutter's `disconnect()` does not wait
for the channel to drain. The JS, Swift and Android SDKs send the Leave
without that wait too, so it is a gap of its own and not part of this
PR.
It has the batch acknowledgement the outgoing pump now uses, and bindings
that free the native buffers of byte and string payloads.
@hiroshihorie
hiroshihorie marked this pull request as ready for review November 19, 2026 00:51

@devin-ai-integration devin-ai-integration 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.

🔍 Devin Review: 1 flag

Not posted on this PR by your GitHub settings — view it in Devin Review. (Configure)

Devin Review

@hiroshihorie
hiroshihorie merged commit ca8e1c0 into main Nov 19, 2026
16 checks passed
@hiroshihorie
hiroshihorie deleted the hiroshi/data-streams-polled-ack branch November 19, 2026 02:30
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