Skip to content

Data streams: port writers to FFI writer handles; add streamText / streamBytes - #322

Draft
1egoman wants to merge 1 commit into
data-streams-ffi-receive-and-sendfrom
data-streams-ffi-writers
Draft

1egoman wants to merge 1 commit into
data-streams-ffi-receive-and-sendfrom
data-streams-ffi-writers

Conversation

@1egoman

@1egoman 1egoman commented Nov 20, 2026

Copy link
Copy Markdown

Stacked on #321; review that one first. This PR's base is #321's branch, so the diff shows only the writer port.

Second half of the data streams port. TextStreamWriter / ByteStreamWriter now use FFI writer handles (text/byte_stream_open, *_stream_write, *_stream_close) instead of hand-built header, chunk and trailer packets. Rust does the chunking and UTF-8 splitting. After #321 the old writers still worked (FFI readers accept v1 framing), so this PR is cleanup and parity rather than a bug fix. It does fix the writer races and disconnect handling described below.

What changes

  • New factories LocalParticipant::streamText / streamBytes. They return an already-open writer, blocking until the open callback arrives, and throw DataStreamError on failure. This matches the other SDKs' stream_text / stream_bytes.
  • Writer constructors are deprecated. They keep their exact signatures and still work, opening lazily on the first write() / close() as the header did before. Each carries both [[deprecated]] and /// @deprecated, per AGENTS.md.
  • Ordering. write() and close() share one mutex, and each waits for its FFI callback, so close() never overtakes an in-flight write (python-sdks#879). This also fixes close() previously not taking the write lock.
  • Disconnect. A LocalParticipant tracks its writers in a registry it shares with them. On disconnect, or when the participant is destroyed, every writer is closed and its handle dropped. Later write() / close() throw DataStreamError instead of reaching an FFI session that would panic (the C++ SDK turns an FFI panic into SIGTERM). Because the registry is shared, a writer that outlives its participant never touches the dead participant. Python still has this bug: a disposed writer there looks usable.
  • Destroyed without close(). The writer sends a non-waiting FFI close. Rust's RawStream only sends its drop-time trailer when dropped on a Tokio thread (Handle::try_current()). A handle drop from C++ runs on a C++ thread, so the trailer was silently skipped and receivers waited forever. I confirmed this by swapping the close for a plain drop: WriterDestroyedWithoutCloseEndsStream then hangs.
  • Deprecations. kStreamChunkSize and the protected ensureHeaderSent / sendChunk / sendTrailer helpers are deprecated; it's source API for subclasses. The helpers are reimplemented on the new path (open, write, close). The protected data members stay.
  • Stream ids are still generated in C++ when not given, so streamId() works before open. Text total_size is documented as local only, because the FFI can't transmit it.
  • Removed: FfiClient::sendStream*Async and their unit tests, splitUtf8, and the now-unused header, chunk and trailer converters. The public DataStream* event structs and RoomDelegate callbacks are kept.

API compatibility: source compatible. Existing code compiles unchanged, with deprecation warnings. ABI changes: writer class layout, and closed_ is now std::atomic<bool>.

Testing

All runs were local on macOS arm64, against livekit-server --dev with sourced tokens.

  • Unit tests: 383/383 pass. New coverage:
    • FfiClient writer helpers throw when the FFI isn't initialized
    • the factories throw when the FFI isn't initialized
    • the deprecated constructors keep their metadata
    • writers close when their participant goes away, without touching the destroyed participant
  • Integration, DataStreamE2ETest: 24/24 pass. Existing tests moved to the factories. New tests:
    • incremental Unicode text across chunk boundaries
    • 1 MB patterned and 1 MB incompressible byte streams with total_length
    • close() racing an in-flight 2 MB write (no data lost)
    • write after close
    • write and close after disconnect, with the receiver getting an error rather than hanging
    • writer destroyed without close()
    • one test that deliberately keeps using the deprecated constructors (warning silenced locally)
  • Repeat runs: the writer tests were repeated 5× with no failures.
  • Full integration suite: 89 pass, 1 skipped. The same 5 tests fail as on main on this machine (data track schema ×3, server-deleted room, platform audio device); see Data streams: receive via FFI readers; add sendText / sendBytes / sendFile #321.
  • Stress: RoomStressTest / RoomServerStressTest pass 6/6.
  • Cross-SDK check (manual). A Python receiver (PyPI livekit 1.3.0) got the C++ streamText (two writes, 40,012 bytes), sendText (50 KB) and streamBytes (100,000 bytes) intact.
  • Tooling: the Doxygen build is clean, the symbol leak check passes on a release build, clang-format is clean, and clang-tidy reports nothing on added lines.
  • No benchmark: left out per the plan, despite the general AGENTS.md guidance.

Not in this PR

  • The cpp-example-collection/simple_data_stream move to streamText / streamBytes is deferred and will be a follow-up.

🤖 Generated with Claude Code

…Bytes

TextStreamWriter / ByteStreamWriter now open an FFI writer
(text/byte_stream_open) and send through text/byte_stream_write and
*_stream_close instead of hand-built header/chunk/trailer packets. Rust does
the chunking and UTF-8 splitting.

- LocalParticipant::streamText / streamBytes return an already-open writer
  (blocking until the open callback, throwing DataStreamError on failure).
  The public writer constructors keep working but are deprecated; they open
  lazily on the first write or close, as the header did before.
- write() and close() share one mutex and each waits for its FFI callback,
  so a close never overtakes an in-flight write (python-sdks#879); this also
  fixes close() not taking the write lock.
- A LocalParticipant tracks its writers in a registry shared with them. On
  disconnect (or participant destruction) every writer is closed and its
  handle dropped, so later write/close throw DataStreamError instead of
  reaching an FFI session that would panic.
- A writer destroyed without close() sends a non-waiting FFI close. Rust's
  writer only sends its drop-time trailer from a Tokio thread, so a plain
  handle drop from C++ left receivers waiting forever.
- kStreamChunkSize and the protected ensureHeaderSent / sendChunk /
  sendTrailer helpers are deprecated and reimplemented on the new path.
- Removed FfiClient::sendStream*Async, splitUtf8 and the now-unused
  header/chunk/trailer converters.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
/// @param reply_to_id Id of the stream this one replies to, or empty.
/// @param destination_identities Recipients; empty for everyone.
/// @param sender_identity Identity to send as; defaults to the local participant.
[[deprecated("Constructing TextStreamWriter directly is deprecated; use LocalParticipant::streamText instead")]]

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

Open question: this deprecates constructing TextStreamWriter / ByteStreamWriter directly in favour of LocalParticipant::streamText / streamBytes, to match the other SDKs. The constructors keep working. Is deprecating them the right call, or should both stay first-class?

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