From beb795d21e49b36a0614adbf48732d1e04b68e07 Mon Sep 17 00:00:00 2001 From: Ryan Gaus Date: Fri, 20 Nov 2026 13:18:00 +1300 Subject: [PATCH] Port data stream receive path to FFI readers; add sendText/sendBytes/sendFile Incoming data streams were rebuilt from the low-level stream_header/chunk/ trailer events. Since livekit-ffi 0.15.0 always advertises data streams v2, modern senders send C++ participants single-packet and deflate-compressed streams, which that path can't read: inline streams hang readAll() forever and compressed chunks arrive as raw deflate bytes. The FFI also handed C++ an owned reader handle for every incoming stream, which C++ ignored, so every stream's content stayed buffered in the FFI for the life of the process. Receive: - Room consumes text/byte_stream_opened: unhandled topics drop the reader handle; handled topics start read_incremental and route the resulting *_stream_reader_events (keyed by reader handle) to the reader. The low-level stream_*_received events are now ignored. - Readers surface abnormal ends (sender close reason, size limit, disconnect) as DataStreamError after draining buffered chunks, merge end-of-stream attributes into info() on the reading thread, gain close(), and ByteStreamReader gains readAll(). Room shutdown wakes blocked readers. - RoomOptions::data_stream.max_payload_byte_length sets the receive limit. Send: - LocalParticipant::sendText / sendBytes / sendFile use the FFI one-shot sends (compression and single-packet delivery when recipients support them). They throw DataStreamError on failure and refuse to reach the FFI once the room has disconnected, since the FFI panics there. TextStreamOpenedEvent / ByteStreamOpenedEvent::reader_handle stays 0 and is documented as deprecated. Existing writers are unchanged (v1 framing is still accepted by FFI readers). Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 4 +- CMakeLists.txt | 2 + README.md | 4 +- include/livekit/data_stream.h | 249 +++++++++-- include/livekit/local_participant.h | 56 +++ include/livekit/room.h | 42 +- include/livekit/room_event_types.h | 12 +- src/data_stream.cpp | 178 +++++--- src/data_stream_proto_converter.cpp | 111 +++++ src/data_stream_proto_converter.h | 45 ++ src/ffi_client.cpp | 148 +++++++ src/ffi_client.h | 23 +- src/local_participant.cpp | 47 +++ src/room.cpp | 317 ++++++++------ src/room_proto_converter.cpp | 11 +- src/tests/integration/test_data_streams.cpp | 435 +++++++++++++++++++- src/tests/unit/test_data_stream.cpp | 307 ++++++++++++++ 17 files changed, 1758 insertions(+), 233 deletions(-) create mode 100644 src/data_stream_proto_converter.cpp create mode 100644 src/data_stream_proto_converter.h diff --git a/AGENTS.md b/AGENTS.md index d9daf703..9901a51a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -56,7 +56,7 @@ The SDK has three categories of threads: 1. Completes any pending async `std::promise` matched by `async_id`. 2. Invokes all registered `FfiClient` listeners (including `Room::onEvent`). -All `RoomDelegate` callbacks and stream handler callbacks (e.g., `registerTextStreamHandler`) are invoked on this FFI callback thread. **Handlers must not block**; spawn a background thread if synchronous work is needed. +All `RoomDelegate` callbacks and stream handler callbacks (e.g., `registerTextStreamHandler`) are invoked on this FFI callback thread. **Handlers must not block**; spawn a background thread if synchronous work is needed. Incoming data stream chunks are also delivered to `TextStreamReader` / `ByteStreamReader` on this thread (routed by `Room` from `*_stream_reader_event`s keyed by reader handle), so a stream handler must never call `readNext()` / `readAll()` inline; readers log a warning if they would block on the FFI callback thread. **Per-subscription reader threads** — `SubscriptionThreadDispatcher` creates a dedicated `std::thread` for each active audio, video, or data track subscription. These threads block on `AudioStream::read()`, `VideoStream::read()`, or `DataTrackStream::read()` and invoke the registered `AudioFrameCallback`, `VideoFrameCallback`, or `DataFrameCallback` on that reader thread — not on the FFI callback thread. A hard limit of 20 concurrent reader threads is enforced. @@ -76,6 +76,8 @@ All `RoomDelegate` callbacks and stream handler callbacks (e.g., `registerTextSt | `VideoSource::captureFrame` | No | Not safe to call concurrently from multiple threads. | | `LocalAudioTrack` / `LocalVideoTrack` | No | Thin `sendRequest` wrappers with no internal synchronization. | | `LocalDataTrack::tryPush` | No | Thin `sendRequest` wrapper with no internal synchronization. | +| `TextStreamReader` / `ByteStreamReader` | Yes | Fed on the FFI callback thread, read on a user thread (internal `std::mutex` + `condition_variable`). End-of-stream attributes are merged into `info()` on the reading thread, so don't call `info()` concurrently with `readNext()`. | +| `LocalParticipant::sendText` / `sendBytes` / `sendFile` | Yes | Independent async FFI requests; each call blocks its caller until its own callback arrives. They throw `DataStreamError` once the room has disconnected rather than reaching the FFI. | | `TextStreamWriter` / `ByteStreamWriter` | Serialized | `write()` is serialized by an internal `write_mutex_`. | ### Directory Layout diff --git a/CMakeLists.txt b/CMakeLists.txt index 00d4bd32..17a1fcef 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -422,6 +422,8 @@ add_library(livekit SHARED src/audio_stream.cpp src/data_track_frame.cpp src/data_stream.cpp + src/data_stream_proto_converter.cpp + src/data_stream_proto_converter.h src/data_track_error.cpp src/data_track_schema.cpp src/data_track_stream.cpp diff --git a/README.md b/README.md index 243e1d3a..4bf10eb8 100644 --- a/README.md +++ b/README.md @@ -226,7 +226,9 @@ token source helpers for endpoint, development token server, and custom backends - Dynamic token sourcing (literal, custom, endpoint, development token server, caching) - Receive remote audio/video tracks - Publish local audio/video tracks -- Data tracks (low-level) and data streams (high-level) +- Data tracks (low-level) and data streams (high-level): one-shot `sendText` / + `sendBytes` / `sendFile` with compression, incremental writers, and + per-topic stream handlers - RPC between participants - End-to-end encryption (E2EE) - Hardware-accelerated codecs (via the underlying Rust SDK) diff --git a/include/livekit/data_stream.h b/include/livekit/data_stream.h index 173b8b0d..8d02b41c 100644 --- a/include/livekit/data_stream.h +++ b/include/livekit/data_stream.h @@ -24,6 +24,7 @@ #include #include #include +#include #include #include @@ -38,6 +39,100 @@ class LocalParticipant; /// channels. constexpr std::size_t kStreamChunkSize = 15'000; // 15 KB +/// @brief Error raised by data stream operations. +/// +/// Thrown by the one-shot send APIs (for example +/// LocalParticipant::sendText()) when the send fails or the participant is no +/// longer connected, and by TextStreamReader / ByteStreamReader when an +/// incoming stream ends abnormally (for example the sender closed it with a +/// reason, the stream exceeded RoomOptions::data_stream limits, or the room +/// disconnected mid-stream). The message carries the SDK's error description. +/// +/// Derives from std::runtime_error, so existing +/// `catch (const std::runtime_error&)` handlers keep working. +class LIVEKIT_API DataStreamError : public std::runtime_error { +public: + /// @brief Construct an error with a description. + /// @param message Human-readable error description. + explicit DataStreamError(const std::string& message); +}; + +/// @brief Options for a one-shot text send or an incremental text stream. +/// +/// Used by LocalParticipant::sendText(). +struct StreamTextOptions { + /// Application-defined topic. Required; receivers route streams to handlers + /// registered with Room::registerTextStreamHandler() by topic. + std::string topic; + + /// Arbitrary key/value attributes sent with the stream header. + std::map attributes; + + /// Identities of the participants that should receive the stream. Empty + /// means every participant in the room. + std::vector destination_identities; + + /// Stream id to use. A unique id is generated when unset. + std::optional stream_id; + + /// Id of the stream this stream replies to, if any. + std::optional reply_to_stream_id; + + /// Ids of other streams (for example files) attached to this text stream. + std::vector attached_stream_ids; + + /// Compress the payload when every recipient supports compression. + /// + /// Only one-shot sends compress; incremental writers ignore this flag. + bool compress = true; + + /// Identity to send as. Leave unset to send as the local participant; + /// setting it requires the impersonation permission. + std::optional sender_identity; +}; + +/// @brief Options for a one-shot byte/file send or an incremental byte stream. +/// +/// Used by LocalParticipant::sendBytes() and LocalParticipant::sendFile(). +struct StreamByteOptions { + /// Application-defined topic. Required; receivers route streams to handlers + /// registered with Room::registerByteStreamHandler() by topic. + std::string topic; + + /// Arbitrary key/value attributes sent with the stream header. + std::map attributes; + + /// Identities of the participants that should receive the stream. Empty + /// means every participant in the room. + std::vector destination_identities; + + /// Stream id to use. A unique id is generated when unset. + std::optional stream_id; + + /// Name of the payload (for example a file name). When unset, sendBytes() + /// uses the SDK default ("unknown") and sendFile() uses the file's basename. + std::optional name; + + /// MIME type of the payload. When unset, the SDK picks a default + /// ("application/octet-stream" for bytes; derived from the file for + /// sendFile()). + std::optional mime_type; + + /// Total payload size in bytes, if known. Only meaningful for incremental + /// writers; one-shot sends always know their size. + std::optional total_length; + + /// Compress the payload when every recipient supports compression. + /// + /// Only one-shot sends compress; incremental writers ignore this flag. Turn + /// it off for payloads that are already compressed (images, video, archives). + bool compress = true; + + /// Identity to send as. Leave unset to send as the local participant; + /// setting it requires the impersonation permission. + std::optional sender_identity; +}; + /// Base metadata for any stream (text or bytes). struct BaseStreamInfo { /// Unique identifier for this stream. @@ -77,80 +172,156 @@ struct ByteStreamInfo : BaseStreamInfo { // - TextStreamReader: yields UTF-8 text chunks (std::string) // - ByteStreamReader: yields raw bytes (std::vector) -/// Reader for incoming text streams. -/// Created internally by the SDK when a text stream header is received. +/// @brief Reader for incoming text streams. +/// +/// Created by the SDK when a remote participant opens a text stream on a topic +/// with a handler registered via Room::registerTextStreamHandler(). The SDK +/// decompresses and reassembles the stream; each chunk is valid UTF-8. +/// +/// Reading blocks the calling thread. Stream handlers run on the SDK's event +/// thread, which also delivers the chunks, so never read from inside the +/// handler: move the reader to another thread first. class LIVEKIT_API TextStreamReader { public: - /// Construct a reader from initial stream metadata. + /// @brief Construct a detached reader from stream metadata. + /// + /// A reader built this way is not connected to any incoming stream and + /// never receives data. Readers for real streams are created by the SDK. + /// @param info Stream metadata. explicit TextStreamReader(TextStreamInfo info); + ~TextStreamReader(); TextStreamReader(const TextStreamReader&) = delete; TextStreamReader& operator=(const TextStreamReader&) = delete; - /// Blocking read of next text chunk. - /// Returns false when the stream has ended. + /// @brief Blocking read of the next text chunk. + /// + /// When the stream ends normally, any final attributes the sender attached + /// on close are merged into info().attributes before this returns false. + /// + /// @param out Receives the next chunk. + /// @return True if a chunk was read; false when the stream has ended or + /// close() was called. + /// @throws DataStreamError if the stream ended abnormally (for example the + /// sender closed it with a reason, it exceeded the receive size + /// limit, or the room disconnected mid-stream). Chunks received + /// before the error are returned first. bool readNext(std::string& out); - /// Convenience: read entire stream into a single string. - /// Blocks until the stream is closed. + /// @brief Read the entire stream into a single string. + /// + /// Blocks until the stream ends. + /// + /// @return The concatenated text. + /// @throws DataStreamError if the stream ended abnormally. std::string readAll(); - /// Metadata associated with this stream. + /// @brief Stop reading early. + /// + /// Discards buffered chunks and wakes any thread blocked in readNext() or + /// readAll(), which then return the end of the stream. Idempotent. + void close(); + + /// @brief Metadata associated with this stream. + /// + /// Attributes the sender attached when closing the stream are merged in + /// once readNext() or readAll() has reached the end of the stream, on the + /// reading thread. Don't call this concurrently with readNext() from + /// another thread. + /// + /// @return Stream metadata. const TextStreamInfo& info() const noexcept { return info_; } private: friend class Room; + friend struct DataStreamReaderTestAccess; + struct Impl; - /// Called by the Room when a new chunk arrives. - void onChunkUpdate(const std::string& text); + /// Called by the Room when a chunk arrives. + void onChunkReceived(std::string text); - /// Called by the Room when the stream is closed. - /// Additional trailer attributes are merged into info().attributes. - void onStreamClose(const std::map& trailer_attrs); + /// Called by the Room when the stream ends. @p error is set when the stream + /// ended abnormally. + void onStreamEnded(const std::map& attributes, std::optional error); TextStreamInfo info_; - - // Queue of text chunks; empty string with closed_==true means EOS. - std::deque queue_; - bool closed_ = false; - - std::mutex mutex_; - std::condition_variable cv_; + std::unique_ptr impl_; }; -/// Reader for incoming byte streams. +/// @brief Reader for incoming byte streams. +/// +/// Created by the SDK when a remote participant opens a byte stream on a topic +/// with a handler registered via Room::registerByteStreamHandler(). The SDK +/// decompresses and reassembles the stream. +/// +/// Reading blocks the calling thread. Stream handlers run on the SDK's event +/// thread, which also delivers the chunks, so never read from inside the +/// handler: move the reader to another thread first. class LIVEKIT_API ByteStreamReader { public: - /// Construct a reader from initial stream metadata. + /// @brief Construct a detached reader from stream metadata. + /// + /// A reader built this way is not connected to any incoming stream and + /// never receives data. Readers for real streams are created by the SDK. + /// @param info Stream metadata. explicit ByteStreamReader(ByteStreamInfo info); + ~ByteStreamReader(); ByteStreamReader(const ByteStreamReader&) = delete; ByteStreamReader& operator=(const ByteStreamReader&) = delete; - /// Blocking read of next byte chunk. - /// Returns false when the stream has ended. + /// @brief Blocking read of the next byte chunk. + /// + /// When the stream ends normally, any final attributes the sender attached + /// on close are merged into info().attributes before this returns false. + /// + /// @param out Receives the next chunk. + /// @return True if a chunk was read; false when the stream has ended or + /// close() was called. + /// @throws DataStreamError if the stream ended abnormally (for example the + /// sender closed it with a reason, it exceeded the receive size + /// limit, or the room disconnected mid-stream). Chunks received + /// before the error are returned first. bool readNext(std::vector& out); - /// Metadata associated with this stream. + /// @brief Read the entire stream into a single buffer. + /// + /// Blocks until the stream ends. + /// + /// @return The concatenated bytes. + /// @throws DataStreamError if the stream ended abnormally. + std::vector readAll(); + + /// @brief Stop reading early. + /// + /// Discards buffered chunks and wakes any thread blocked in readNext() or + /// readAll(), which then return the end of the stream. Idempotent. + void close(); + + /// @brief Metadata associated with this stream. + /// + /// Attributes the sender attached when closing the stream are merged in + /// once readNext() or readAll() has reached the end of the stream, on the + /// reading thread. Don't call this concurrently with readNext() from + /// another thread. + /// + /// @return Stream metadata. const ByteStreamInfo& info() const noexcept { return info_; } private: friend class Room; + friend struct DataStreamReaderTestAccess; + struct Impl; - /// Called by the Room when a new chunk arrives. - void onChunkUpdate(const std::vector& bytes); + /// Called by the Room when a chunk arrives. + void onChunkReceived(std::vector bytes); - /// Called by the Room when the stream is closed. - /// Additional trailer attributes are merged into info().attributes. - void onStreamClose(const std::map& trailer_attrs); + /// Called by the Room when the stream ends. @p error is set when the stream + /// ended abnormally. + void onStreamEnded(const std::map& attributes, std::optional error); ByteStreamInfo info_; - - std::deque> queue_; - bool closed_ = false; - - std::mutex mutex_; - std::condition_variable cv_; + std::unique_ptr impl_; }; /// Base class for sending data streams. @@ -267,7 +438,8 @@ class LIVEKIT_API ByteStreamWriter : public BaseStreamWriter { /// /// The TextStreamReader is provided as a shared_ptr to ensure it remains /// alive for the duration of asynchronous reads (for example, when the -/// user spawns a background thread to consume the stream). +/// user spawns a background thread to consume the stream). The handler runs on +/// the SDK event thread and must not read from the stream itself. using TextStreamHandler = std::function, const std::string& participant_identity)>; @@ -275,7 +447,8 @@ using TextStreamHandler = /// /// The ByteStreamReader is provided as a shared_ptr to ensure it remains /// alive for the duration of asynchronous reads (for example, file writes -/// or background processing). +/// or background processing). The handler runs on the SDK event thread and +/// must not read from the stream itself. using ByteStreamHandler = std::function, const std::string& participant_identity)>; diff --git a/include/livekit/local_participant.h b/include/livekit/local_participant.h index 557205b0..c9ff7c10 100644 --- a/include/livekit/local_participant.h +++ b/include/livekit/local_participant.h @@ -27,6 +27,7 @@ #include #include +#include "livekit/data_stream.h" #include "livekit/data_track_error.h" #include "livekit/data_track_options.h" #include "livekit/data_track_schema.h" @@ -93,6 +94,49 @@ class LIVEKIT_API LocalParticipant : public Participant { void publishData(const std::vector& payload, bool reliable = true, const std::vector& destination_identities = {}, const std::string& topic = {}); + /// @brief Send a complete text message as a data stream. + /// + /// Blocks until the SDK reports the send complete. When every recipient + /// supports it, small messages go out as a single packet and the payload is + /// compressed (unless @c options.compress is false). Receivers get the + /// message through Room::registerTextStreamHandler() on @c options.topic. + /// + /// @param text UTF-8 text to send. + /// @param options Topic (required), destinations, attributes, and so on. + /// @return Metadata of the sent stream, including its stream id. + /// @throws DataStreamError if the send fails, or if the room is no longer + /// connected or the SDK isn't initialized. + TextStreamInfo sendText(const std::string& text, const StreamTextOptions& options); + + /// @brief Send a complete in-memory buffer as a byte data stream. + /// + /// Blocks until the SDK reports the send complete. When every recipient + /// supports it, small payloads go out as a single packet and the payload is + /// compressed (unless @c options.compress is false). Receivers get the data + /// through Room::registerByteStreamHandler() on @c options.topic. + /// + /// @param data Bytes to send. + /// @param options Topic (required), name, MIME type, destinations, and so on. + /// @return Metadata of the sent stream, including its stream id. + /// @throws DataStreamError if the send fails, or if the room is no longer + /// connected or the SDK isn't initialized. + ByteStreamInfo sendBytes(const std::vector& data, const StreamByteOptions& options); + + /// @brief Send a local file as a byte data stream. + /// + /// The SDK reads the file itself (in this process). Blocks until the send + /// completes. When @c options.name is unset, the file's basename is used. + /// When @c options.mime_type is unset, the SDK picks one from the file. + /// Consider setting @c options.compress to false for files that are + /// already compressed, such as images. + /// + /// @param path Path of the file to send (UTF-8). + /// @param options Topic (required), name, MIME type, destinations, and so on. + /// @return Metadata of the sent stream, including its stream id. + /// @throws DataStreamError if the file can't be read or the send fails, or + /// if the room is no longer connected or the SDK isn't initialized. + ByteStreamInfo sendFile(const std::string& path, const StreamByteOptions& options); + /// Publish a SIP DTMF (phone keypad) tone into the room. /// /// Only meaningful when a SIP trunk is bridging a phone call into the @@ -302,8 +346,20 @@ class LIVEKIT_API LocalParticipant : public Participant { /// prune expired @c weak_ptr entries. mutable TrackMap published_tracks_by_sid_; + /// Marks the participant as disconnected so data stream sends fail fast in + /// C++ instead of reaching an FFI participant whose session is gone. + void markDisconnected() noexcept { disconnected_.store(true, std::memory_order_release); } + + /// Returns the FFI handle id for a data stream operation, or throws + /// DataStreamError if the participant can no longer send. + std::uint64_t dataStreamHandle(const char* operation) const; + std::unordered_map rpc_handlers_; + /// Set once the room disconnects. Guarded by an atomic rather than + /// Room::lock_ so send paths never need the room lock. + std::atomic disconnected_{false}; + // Shared state for RPC invocation tracking. Using shared_ptr so the state // can outlive the LocalParticipant if there are in-flight invocations when // the participant is destroyed. diff --git a/include/livekit/room.h b/include/livekit/room.h index 382006bb..a3ac4b10 100644 --- a/include/livekit/room.h +++ b/include/livekit/room.h @@ -38,7 +38,9 @@ class RoomDelegate; struct RoomInfoData; namespace proto { class FfiEvent; -} +class TextStreamOpened; +class ByteStreamOpened; +} // namespace proto struct E2EEOptions; class E2EEManager; @@ -71,6 +73,15 @@ struct RtcConfig { std::vector ice_servers; }; +/// @brief Data stream settings applied when connecting. +struct DataStreamOptions { + /// Maximum number of (decompressed) bytes accepted per incoming data stream. + /// A stream that exceeds it ends with a DataStreamError on the reader. + /// + /// If unset, the SDK default (5 GB) is used. + std::optional max_payload_byte_length; +}; + /// Top-level room connection options. struct RoomOptions { /// If true (default), automatically subscribe to all remote tracks. @@ -125,6 +136,9 @@ struct RoomOptions { /// If unset, the Rust SDK default is used. std::optional connect_timeout; + /// Data stream settings, such as the incoming stream size limit. + DataStreamOptions data_stream; + /// @cond /// Additional LiveKit SDKs layered on top of this one, reported to the server /// as part of the client info. @@ -267,9 +281,11 @@ class LIVEKIT_API Room { /// - Only one handler may be registered per topic. /// - If no handler is registered for a topic, incoming streams with that /// topic are ignored. - /// - The handler is invoked on the Room event thread. The handler must - /// not block; spawn a background thread if synchronous reading is - /// required. + /// - The handler is invoked on the SDK event thread, which also delivers + /// the stream's chunks. The handler must not block: never call + /// TextStreamReader::readNext() or readAll() inside it. Hand the reader + /// to a background thread instead. + /// - Reading throws DataStreamError if the stream ends abnormally. /// /// @throws std::runtime_error if a handler is already registered for the topic. void registerTextStreamHandler(const std::string& topic, TextStreamHandler handler); @@ -292,6 +308,11 @@ class LIVEKIT_API Room { /// topic are ignored. /// - The ByteStreamReader remains valid as long as the shared_ptr is held, /// preventing lifetime-related crashes when reading asynchronously. + /// - The handler is invoked on the SDK event thread, which also delivers + /// the stream's chunks. The handler must not block: never call + /// ByteStreamReader::readNext() or readAll() inside it. Hand the reader + /// to a background thread instead. + /// - Reading throws DataStreamError if the stream ends abnormally. /// /// @throws std::runtime_error if a handler is already registered for the topic. void registerByteStreamHandler(const std::string& topic, ByteStreamHandler handler); @@ -357,8 +378,12 @@ class LIVEKIT_API Room { // Data stream std::unordered_map text_stream_handlers_; std::unordered_map byte_stream_handlers_; - std::unordered_map> text_stream_readers_; - std::unordered_map> byte_stream_readers_; + // Active incoming stream readers, keyed by FFI reader handle id. A reader is + // removed when its end-of-stream event arrives or the room shuts down. + using TextStreamReaderMap = std::unordered_map>; + using ByteStreamReaderMap = std::unordered_map>; + TextStreamReaderMap text_stream_readers_; + ByteStreamReaderMap byte_stream_readers_; // The E2EE manager is owned by the room and is not shared with other objects. // It is a shared_ptr just to utilize the weak_ptr interface for the e2eeManager() accessor. std::shared_ptr e2ee_manager_; @@ -368,6 +393,11 @@ class LIVEKIT_API Room { int listener_id_{0}; void onEvent(const proto::FfiEvent& event); + void onTextStreamOpened(const proto::TextStreamOpened& opened, RoomDelegate* delegate); + void onByteStreamOpened(const proto::ByteStreamOpened& opened, RoomDelegate* delegate); + bool dispatchStreamReaderEvent(const proto::FfiEvent& event); + // Gives every reader a terminal "disconnected" error so blocked reads wake. + static void endStreamReaders(const TextStreamReaderMap& text_readers, const ByteStreamReaderMap& byte_readers); // Shared shutdown path for explicit disconnect, server disconnect, EOS, and destruction. bool shutdown(bool disconnect_ffi, DisconnectReason reason, bool notify_delegate); diff --git a/include/livekit/room_event_types.h b/include/livekit/room_event_types.h index 10fdffce..3e55482a 100644 --- a/include/livekit/room_event_types.h +++ b/include/livekit/room_event_types.h @@ -664,7 +664,11 @@ struct DataChannelBufferedAmountLowThresholdChangedEvent { /// Fired when a high-level byte stream reader is opened. struct ByteStreamOpenedEvent { - /// Handle to the underlying byte stream reader. + /// Always 0. + /// + /// @deprecated The reader handle is owned and consumed by the + /// ByteStreamReader the SDK passes to the handler registered with + /// Room::registerByteStreamHandler(); use that reader instead. std::uint64_t reader_handle = 0; /// Identity of the participant that opened the stream. @@ -673,7 +677,11 @@ struct ByteStreamOpenedEvent { /// Fired when a high-level text stream reader is opened. struct TextStreamOpenedEvent { - /// Handle to the underlying text stream reader. + /// Always 0. + /// + /// @deprecated The reader handle is owned and consumed by the + /// TextStreamReader the SDK passes to the handler registered with + /// Room::registerTextStreamHandler(); use that reader instead. std::uint64_t reader_handle = 0; /// Identity of the participant that opened the stream. diff --git a/src/data_stream.cpp b/src/data_stream.cpp index eb5ed11e..0d88da8e 100644 --- a/src/data_stream.cpp +++ b/src/data_stream.cpp @@ -18,6 +18,9 @@ #include #include +#include +#include +#include #include #include @@ -96,46 +99,125 @@ void fillBaseInfo(BaseStreamInfo& dst, const std::string& stream_id, const std:: } // namespace +// ===================================================================== +// Errors +// ===================================================================== + +DataStreamError::DataStreamError(const std::string& message) : std::runtime_error(message) {} + // ===================================================================== // Reader implementation // ===================================================================== -TextStreamReader::TextStreamReader(TextStreamInfo info) : info_(std::move(info)) {} +namespace { -void TextStreamReader::onChunkUpdate(const std::string& text) { - { - const std::scoped_lock lock(mutex_); - if (closed_) { - return; +/// Shared state for TextStreamReader / ByteStreamReader. +/// +/// The FFI callback thread pushes chunks and the end-of-stream marker; a user +/// thread pops them. Final attributes are merged into the reader's info on the +/// reading thread so info() is never mutated behind a single-threaded reader. +template +class ReaderState { +public: + void push(Chunk chunk) { + { + const std::scoped_lock lock(mutex_); + if (ended_ || closed_) { + return; + } + queue_.push_back(std::move(chunk)); } - queue_.push_back(text); + cv_.notify_one(); } - cv_.notify_one(); -} -void TextStreamReader::onStreamClose(const std::map& trailer_attrs) { - { - const std::scoped_lock lock(mutex_); - for (const auto& kv : trailer_attrs) { - info_.attributes[kv.first] = kv.second; + void end(const std::map& attributes, std::optional error) { + { + const std::scoped_lock lock(mutex_); + if (ended_) { + return; + } + ended_ = true; + end_attributes_ = attributes; + error_ = std::move(error); } - closed_ = true; + cv_.notify_all(); } - cv_.notify_all(); -} -bool TextStreamReader::readNext(std::string& out) { - std::unique_lock lock(mutex_); - cv_.wait(lock, [this] { return !queue_.empty() || closed_; }); + void close() { + { + const std::scoped_lock lock(mutex_); + closed_ = true; + queue_.clear(); + } + cv_.notify_all(); + } - if (!queue_.empty()) { - out = std::move(queue_.front()); - queue_.pop_front(); - return true; + /// Pops the next chunk into @p out. Returns false at the end of the stream. + /// Throws DataStreamError once the queue is drained if the stream failed. + template + bool next(Chunk& out, Info& info, const char* reader_name) { + std::unique_lock lock(mutex_); + if (!closed_ && !ended_ && queue_.empty() && !warned_ffi_thread_ && isOnFfiCallbackThread()) { + warned_ffi_thread_ = true; + LK_LOG_WARN( + "{}::readNext called on the SDK event thread; this blocks event delivery and can deadlock. " + "Read from a separate thread instead.", + reader_name); + } + cv_.wait(lock, [this] { return closed_ || ended_ || !queue_.empty(); }); + + if (closed_) { + return false; + } + if (!queue_.empty()) { + out = std::move(queue_.front()); + queue_.pop_front(); + return true; + } + + // Ended and drained. + if (!attributes_merged_) { + attributes_merged_ = true; + for (const auto& kv : end_attributes_) { + info.attributes[kv.first] = kv.second; + } + } + if (error_) { + throw DataStreamError(*error_); + } + return false; } - return false; // closed_ and empty + +private: + std::mutex mutex_; + std::condition_variable cv_; + std::deque queue_; + std::map end_attributes_; + std::optional error_; + bool ended_ = false; + bool closed_ = false; + bool attributes_merged_ = false; + bool warned_ffi_thread_ = false; +}; + +} // namespace + +struct TextStreamReader::Impl : ReaderState {}; +struct ByteStreamReader::Impl : ReaderState> {}; + +TextStreamReader::TextStreamReader(TextStreamInfo info) : info_(std::move(info)), impl_(std::make_unique()) {} + +TextStreamReader::~TextStreamReader() = default; + +void TextStreamReader::onChunkReceived(std::string text) { impl_->push(std::move(text)); } + +void TextStreamReader::onStreamEnded(const std::map& attributes, + std::optional error) { + impl_->end(attributes, std::move(error)); } +bool TextStreamReader::readNext(std::string& out) { return impl_->next(out, info_, "TextStreamReader"); } + std::string TextStreamReader::readAll() { std::string result; std::string chunk; @@ -145,42 +227,32 @@ std::string TextStreamReader::readAll() { return result; } -ByteStreamReader::ByteStreamReader(ByteStreamInfo info) : info_(std::move(info)) {} +void TextStreamReader::close() { impl_->close(); } -void ByteStreamReader::onChunkUpdate(const std::vector& bytes) { - { - const std::scoped_lock lock(mutex_); - if (closed_) { - return; - } - queue_.push_back(bytes); - } - cv_.notify_one(); -} +ByteStreamReader::ByteStreamReader(ByteStreamInfo info) : info_(std::move(info)), impl_(std::make_unique()) {} -void ByteStreamReader::onStreamClose(const std::map& trailer_attrs) { - { - const std::scoped_lock lock(mutex_); - for (const auto& kv : trailer_attrs) { - info_.attributes[kv.first] = kv.second; - } - closed_ = true; - } - cv_.notify_all(); +ByteStreamReader::~ByteStreamReader() = default; + +void ByteStreamReader::onChunkReceived(std::vector bytes) { impl_->push(std::move(bytes)); } + +void ByteStreamReader::onStreamEnded(const std::map& attributes, + std::optional error) { + impl_->end(attributes, std::move(error)); } -bool ByteStreamReader::readNext(std::vector& out) { - std::unique_lock lock(mutex_); - cv_.wait(lock, [this] { return !queue_.empty() || closed_; }); +bool ByteStreamReader::readNext(std::vector& out) { return impl_->next(out, info_, "ByteStreamReader"); } - if (!queue_.empty()) { - out = std::move(queue_.front()); - queue_.pop_front(); - return true; +std::vector ByteStreamReader::readAll() { + std::vector result; + std::vector chunk; + while (readNext(chunk)) { + result.insert(result.end(), chunk.begin(), chunk.end()); } - return false; + return result; } +void ByteStreamReader::close() { impl_->close(); } + // ===================================================================== // Writer implementation (uses your future-based FfiClient) // ===================================================================== diff --git a/src/data_stream_proto_converter.cpp b/src/data_stream_proto_converter.cpp new file mode 100644 index 00000000..0cb087d3 --- /dev/null +++ b/src/data_stream_proto_converter.cpp @@ -0,0 +1,111 @@ +/* + * Copyright 2026 LiveKit + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#include "data_stream_proto_converter.h" + +namespace livekit { + +proto::StreamTextOptions toProto(const StreamTextOptions& in) { + proto::StreamTextOptions out; + out.set_topic(in.topic); + for (const auto& kv : in.attributes) { + (*out.mutable_attributes())[kv.first] = kv.second; + } + for (const auto& identity : in.destination_identities) { + out.add_destination_identities(identity); + } + if (in.stream_id) { + out.set_id(*in.stream_id); + } + if (in.reply_to_stream_id) { + out.set_reply_to_stream_id(*in.reply_to_stream_id); + } + for (const auto& id : in.attached_stream_ids) { + out.add_attached_stream_ids(id); + } + out.set_compress(in.compress); + if (in.sender_identity) { + out.set_sender_identity(*in.sender_identity); + } + return out; +} + +proto::StreamByteOptions toProto(const StreamByteOptions& in) { + proto::StreamByteOptions out; + out.set_topic(in.topic); + for (const auto& kv : in.attributes) { + (*out.mutable_attributes())[kv.first] = kv.second; + } + for (const auto& identity : in.destination_identities) { + out.add_destination_identities(identity); + } + if (in.stream_id) { + out.set_id(*in.stream_id); + } + if (in.name) { + out.set_name(*in.name); + } + if (in.mime_type) { + out.set_mime_type(*in.mime_type); + } + if (in.total_length) { + out.set_total_length(*in.total_length); + } + out.set_compress(in.compress); + if (in.sender_identity) { + out.set_sender_identity(*in.sender_identity); + } + return out; +} + +TextStreamInfo fromProto(const proto::TextStreamInfo& in) { + TextStreamInfo out; + out.stream_id = in.stream_id(); + out.mime_type = in.mime_type(); + out.topic = in.topic(); + out.timestamp = in.timestamp(); + if (in.has_total_length()) { + out.size = static_cast(in.total_length()); + } + for (const auto& kv : in.attributes()) { + out.attributes.emplace(kv.first, kv.second); + } + for (const auto& id : in.attached_stream_ids()) { + out.attachments.push_back(id); + } + if (in.has_reply_to_stream_id()) { + out.reply_to_stream_id = in.reply_to_stream_id(); + } + return out; +} + +ByteStreamInfo fromProto(const proto::ByteStreamInfo& in) { + ByteStreamInfo out; + out.stream_id = in.stream_id(); + out.mime_type = in.mime_type(); + out.topic = in.topic(); + out.timestamp = in.timestamp(); + if (in.has_total_length()) { + out.size = static_cast(in.total_length()); + } + for (const auto& kv : in.attributes()) { + out.attributes.emplace(kv.first, kv.second); + } + out.name = in.name(); + return out; +} + +} // namespace livekit diff --git a/src/data_stream_proto_converter.h b/src/data_stream_proto_converter.h new file mode 100644 index 00000000..acf3c0ee --- /dev/null +++ b/src/data_stream_proto_converter.h @@ -0,0 +1,45 @@ +/* + * Copyright 2026 LiveKit + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#pragma once + +#include "data_stream.pb.h" +#include "livekit/data_stream.h" +#include "livekit/visibility.h" + +namespace livekit { + +/// @brief Convert one-shot text send options to the FFI proto. +/// @param in C++ options. +/// @return The FFI options; `compress` is always set explicitly. +LIVEKIT_INTERNAL_API proto::StreamTextOptions toProto(const StreamTextOptions& in); + +/// @brief Convert one-shot byte send options to the FFI proto. +/// @param in C++ options. +/// @return The FFI options; `compress` is always set explicitly. +LIVEKIT_INTERNAL_API proto::StreamByteOptions toProto(const StreamByteOptions& in); + +/// @brief Convert FFI text stream metadata to the public info struct. +/// @param in FFI info. +/// @return Public info. +LIVEKIT_INTERNAL_API TextStreamInfo fromProto(const proto::TextStreamInfo& in); + +/// @brief Convert FFI byte stream metadata to the public info struct. +/// @param in FFI info. +/// @return Public info. +LIVEKIT_INTERNAL_API ByteStreamInfo fromProto(const proto::ByteStreamInfo& in); + +} // namespace livekit diff --git a/src/ffi_client.cpp b/src/ffi_client.cpp index 0854def8..ccb70300 100644 --- a/src/ffi_client.cpp +++ b/src/ffi_client.cpp @@ -27,6 +27,7 @@ #include "data_track_proto_converter.h" #include "ffi.pb.h" #include "livekit/build.h" +#include "livekit/data_stream.h" #include "livekit/data_track_error.h" #include "livekit/ffi_handle.h" #include "livekit/room.h" @@ -79,6 +80,8 @@ Result subscribeDataTrackF return Result::failure(SubscribeDataTrackError{code, message}); } +thread_local bool t_in_ffi_callback = false; + std::optional ExtractAsyncId(const proto::FfiEvent& event) { using E = proto::FfiEvent; switch (event.message_case()) { @@ -445,9 +448,13 @@ extern "C" LIVEKIT_INTERNAL_API void ffiEventCallback(const uint8_t* buf, size_t return; } + t_in_ffi_callback = true; FfiClient::instance().pushEvent(event); + t_in_ffi_callback = false; } +bool isOnFfiCallbackThread() noexcept { return t_in_ffi_callback; } + FfiClient::AsyncId FfiClient::generateAsyncId() { return next_async_id_.fetch_add(1, std::memory_order_relaxed); } bool FfiClient::cancelPendingByAsyncId(AsyncId async_id) { @@ -1117,6 +1124,147 @@ std::future FfiClient::performRpcAsync(std::uint64_t local_particip return fut; } +std::future FfiClient::sendTextAsync(std::uint64_t local_participant_handle, + const std::string& text, + const proto::StreamTextOptions& options) { + const AsyncId async_id = generateAsyncId(); + + auto fut = registerAsync( + async_id, + [async_id](const proto::FfiEvent& e) { return e.has_send_text() && e.send_text().async_id() == async_id; }, + [](const proto::FfiEvent& e, std::promise& pr) { + const auto& cb = e.send_text(); + if (cb.has_error()) { + pr.set_exception(std::make_exception_ptr(DataStreamError(cb.error().description()))); + return; + } + if (!cb.has_info()) { + pr.set_exception(std::make_exception_ptr(DataStreamError("send_text callback missing info"))); + return; + } + pr.set_value(cb.info()); + }); + + proto::FfiRequest req; + auto* msg = req.mutable_send_text(); + msg->set_local_participant_handle(local_participant_handle); + *msg->mutable_options() = options; + msg->set_text(text); + msg->set_request_async_id(async_id); + + try { + const proto::FfiResponse resp = sendRequest(req); + if (!resp.has_send_text()) { + logAndThrow("FfiResponse missing send_text"); + } + } catch (...) { + cancelPendingByAsyncId(async_id); + throw; + } + + return fut; +} + +std::future FfiClient::sendBytesAsync(std::uint64_t local_participant_handle, + const std::vector& bytes, + const proto::StreamByteOptions& options) { + const AsyncId async_id = generateAsyncId(); + + auto fut = registerAsync( + async_id, + [async_id](const proto::FfiEvent& e) { return e.has_send_bytes() && e.send_bytes().async_id() == async_id; }, + [](const proto::FfiEvent& e, std::promise& pr) { + const auto& cb = e.send_bytes(); + if (cb.has_error()) { + pr.set_exception(std::make_exception_ptr(DataStreamError(cb.error().description()))); + return; + } + if (!cb.has_info()) { + pr.set_exception(std::make_exception_ptr(DataStreamError("send_bytes callback missing info"))); + return; + } + pr.set_value(cb.info()); + }); + + proto::FfiRequest req; + auto* msg = req.mutable_send_bytes(); + msg->set_local_participant_handle(local_participant_handle); + *msg->mutable_options() = options; + msg->set_bytes(bytes.data(), bytes.size()); + msg->set_request_async_id(async_id); + + try { + const proto::FfiResponse resp = sendRequest(req); + if (!resp.has_send_bytes()) { + logAndThrow("FfiResponse missing send_bytes"); + } + } catch (...) { + cancelPendingByAsyncId(async_id); + throw; + } + + return fut; +} + +std::future FfiClient::sendFileAsync(std::uint64_t local_participant_handle, + const std::string& file_path, + const proto::StreamByteOptions& options) { + const AsyncId async_id = generateAsyncId(); + + auto fut = registerAsync( + async_id, + [async_id](const proto::FfiEvent& e) { return e.has_send_file() && e.send_file().async_id() == async_id; }, + [](const proto::FfiEvent& e, std::promise& pr) { + const auto& cb = e.send_file(); + if (cb.has_error()) { + pr.set_exception(std::make_exception_ptr(DataStreamError(cb.error().description()))); + return; + } + if (!cb.has_info()) { + pr.set_exception(std::make_exception_ptr(DataStreamError("send_file callback missing info"))); + return; + } + pr.set_value(cb.info()); + }); + + proto::FfiRequest req; + auto* msg = req.mutable_send_file(); + msg->set_local_participant_handle(local_participant_handle); + *msg->mutable_options() = options; + msg->set_file_path(file_path); + msg->set_request_async_id(async_id); + + try { + const proto::FfiResponse resp = sendRequest(req); + if (!resp.has_send_file()) { + logAndThrow("FfiResponse missing send_file"); + } + } catch (...) { + cancelPendingByAsyncId(async_id); + throw; + } + + return fut; +} + +void FfiClient::textStreamReadIncremental(std::uint64_t reader_handle) { + proto::FfiRequest req; + req.mutable_text_read_incremental()->set_reader_handle(reader_handle); + const proto::FfiResponse resp = sendRequest(req); + if (!resp.has_text_read_incremental()) { + logAndThrow("FfiResponse missing text_read_incremental"); + } +} + +void FfiClient::byteStreamReadIncremental(std::uint64_t reader_handle) { + proto::FfiRequest req; + req.mutable_byte_read_incremental()->set_reader_handle(reader_handle); + const proto::FfiResponse resp = sendRequest(req); + if (!resp.has_byte_read_incremental()) { + logAndThrow("FfiResponse missing byte_read_incremental"); + } +} + std::future FfiClient::sendStreamHeaderAsync(std::uint64_t local_participant_handle, const proto::DataStream::Header& header, const std::vector& destination_identities, diff --git a/src/ffi_client.h b/src/ffi_client.h index 3183786a..1359f891 100644 --- a/src/ffi_client.h +++ b/src/ffi_client.h @@ -77,6 +77,11 @@ extern "C" LIVEKIT_INTERNAL_API void ffiEventCallback(const uint8_t* buf, size_t /// @return True if the handle was released; false if it did not exist. [[nodiscard]] LIVEKIT_INTERNAL_API bool dropFfiHandle(std::uint64_t handle) noexcept; +/// @brief Whether the calling thread is currently delivering an FFI event. +/// Used to warn about blocking calls made from SDK callbacks. +/// @return True if called from inside ffiEventCallback. +[[nodiscard]] LIVEKIT_INTERNAL_API bool isOnFfiCallbackThread() noexcept; + // The FfiClient is used to communicate with the FFI interface of the Rust SDK // We use the generated protocol messages to facilitate the communication. class LIVEKIT_INTERNAL_API FfiClient { @@ -155,7 +160,23 @@ class LIVEKIT_INTERNAL_API FfiClient { Result subscribeDataTrack( std::uint64_t track_handle, std::optional buffer_size = std::nullopt); - // Data stream functionalities + // Data stream APIs (high-level; Rust handles framing, chunking and + // compression). A callback error is surfaced as DataStreamError. + std::future sendTextAsync(std::uint64_t local_participant_handle, const std::string& text, + const proto::StreamTextOptions& options); + std::future sendBytesAsync(std::uint64_t local_participant_handle, + const std::vector& bytes, + const proto::StreamByteOptions& options); + std::future sendFileAsync(std::uint64_t local_participant_handle, const std::string& file_path, + const proto::StreamByteOptions& options); + + // Start incremental reads of an owned reader handle. Consumes the handle: + // never drop it afterwards. Chunks and EOS arrive as + // Text/ByteStreamReaderEvent keyed by reader handle. + void textStreamReadIncremental(std::uint64_t reader_handle); + void byteStreamReadIncremental(std::uint64_t reader_handle); + + // Low-level data stream functionalities (legacy v1 framing) std::future sendStreamHeaderAsync(std::uint64_t local_participant_handle, const proto::DataStream::Header& header, const std::vector& destination_identities, diff --git a/src/local_participant.cpp b/src/local_participant.cpp index 2607963d..e93e3fcc 100644 --- a/src/local_participant.cpp +++ b/src/local_participant.cpp @@ -21,6 +21,7 @@ #include #include +#include "data_stream_proto_converter.h" #include "data_track.pb.h" #include "ffi.pb.h" #include "ffi_client.h" @@ -86,6 +87,51 @@ void LocalParticipant::publishData(const std::vector& payload, boo fut.get(); } +std::uint64_t LocalParticipant::dataStreamHandle(const char* operation) const { + if (!FfiClient::instance().isInitialized()) { + throw DataStreamError(std::string("LocalParticipant::") + operation + ": LiveKit is not initialized"); + } + // The FFI panics (and the SDK raises SIGTERM) if a stream is sent after the + // room session is gone, so refuse here instead. + if (disconnected_.load(std::memory_order_acquire)) { + throw DataStreamError(std::string("LocalParticipant::") + operation + ": not connected"); + } + const auto handle_id = ffiHandleId(); + if (handle_id == 0) { + throw DataStreamError(std::string("LocalParticipant::") + operation + ": invalid FFI handle"); + } + return static_cast(handle_id); +} + +TextStreamInfo LocalParticipant::sendText(const std::string& text, const StreamTextOptions& options) { + const auto handle_id = dataStreamHandle("sendText"); + auto fut = FfiClient::instance().sendTextAsync(handle_id, text, toProto(options)); + return fromProto(fut.get()); +} + +ByteStreamInfo LocalParticipant::sendBytes(const std::vector& data, const StreamByteOptions& options) { + const auto handle_id = dataStreamHandle("sendBytes"); + auto fut = FfiClient::instance().sendBytesAsync(handle_id, data, toProto(options)); + return fromProto(fut.get()); +} + +ByteStreamInfo LocalParticipant::sendFile(const std::string& path, const StreamByteOptions& options) { + const auto handle_id = dataStreamHandle("sendFile"); + proto::StreamByteOptions proto_options = toProto(options); + if (!options.name) { + // Basename of a UTF-8 path. Done on the string rather than via + // std::filesystem so non-ASCII names survive on Windows. +#ifdef _WIN32 + const auto slash = path.find_last_of("/\\"); +#else + const auto slash = path.find_last_of('/'); +#endif + proto_options.set_name(slash == std::string::npos ? path : path.substr(slash + 1)); + } + auto fut = FfiClient::instance().sendFileAsync(handle_id, path, proto_options); + return fromProto(fut.get()); +} + void LocalParticipant::publishDtmf(int code, const std::string& digit) { auto handle_id = ffiHandleId(); if (handle_id == 0) { @@ -394,6 +440,7 @@ void LocalParticipant::unregisterRpcMethod(const std::string& method_name) { } void LocalParticipant::shutdown() { + markDisconnected(); // Mark as shutting down and wait for all active invocations to complete { std::unique_lock lock(rpc_state_->mutex); diff --git a/src/room.cpp b/src/room.cpp index 99b39b97..437d0e94 100644 --- a/src/room.cpp +++ b/src/room.cpp @@ -16,6 +16,7 @@ #include "livekit/room.h" +#include "data_stream_proto_converter.h" #include "ffi.pb.h" #include "ffi_client.h" #include "livekit/audio_stream.h" @@ -87,6 +88,16 @@ void readyForRoomEvent(std::uint64_t room_handle) { } } +constexpr char kDisconnectedWhileReceiving[] = "Disconnected while receiving"; + +std::map toStdMap(const google::protobuf::Map& in) { + std::map out; + for (const auto& kv : in) { + out.emplace(kv.first, kv.second); + } + return out; +} + } // namespace Room::Room() : subscription_thread_dispatcher_(std::make_unique()) {} @@ -202,6 +213,8 @@ bool Room::connect(const std::string& url, const std::string& token, const RoomO } catch (const std::exception& e) { int listener_to_remove = 0; std::shared_ptr local_participant_to_cleanup; + TextStreamReaderMap text_readers_to_end; + ByteStreamReaderMap byte_readers_to_end; { const std::scoped_lock g(lock_); connection_state_ = ConnectionState::Disconnected; @@ -213,9 +226,12 @@ bool Room::connect(const std::string& url, const std::string& token, const RoomO remote_participants_.clear(); room_handle_.reset(); e2ee_manager_.reset(); + text_readers_to_end = std::move(text_stream_readers_); + byte_readers_to_end = std::move(byte_stream_readers_); text_stream_readers_.clear(); byte_stream_readers_.clear(); } + endStreamReaders(text_readers_to_end, byte_readers_to_end); if (local_participant_to_cleanup) { local_participant_to_cleanup->shutdown(); } @@ -238,8 +254,8 @@ bool Room::shutdown(bool disconnect_ffi, DisconnectReason reason, bool notify_de std::shared_ptr local_participant_to_cleanup; std::unordered_map> remote_participants_to_clear; std::shared_ptr e2ee_manager_to_clear; - std::unordered_map> text_stream_readers_to_clear; - std::unordered_map> byte_stream_readers_to_clear; + TextStreamReaderMap text_stream_readers_to_clear; + ByteStreamReaderMap byte_stream_readers_to_clear; int listener_to_remove = 0; bool claimed_disconnect = false; @@ -317,6 +333,10 @@ bool Room::shutdown(bool disconnect_ffi, DisconnectReason reason, bool notify_de } } + // Wake readers still waiting on data. Their handles were consumed by + // read_incremental, so there is nothing to drop. + endStreamReaders(text_stream_readers_to_clear, byte_stream_readers_to_clear); + local_participant_to_cleanup.reset(); remote_participants_to_clear.clear(); e2ee_manager_to_clear.reset(); @@ -477,6 +497,11 @@ void Room::onEvent(const FfiEvent& event) { delegate_snapshot = delegate_; } + // Incoming data stream chunks / end-of-stream for readers this room owns. + if (dispatchStreamReaderEvent(event)) { + return; + } + // First, handle RPC method invocations (not part of RoomEvent). if (event.message_case() == FfiEvent::kRpcMethodInvocation) { const auto& rpc = event.rpc_method_invocation(); @@ -1251,6 +1276,9 @@ void Room::onEvent(const FfiEvent& event) { bool should_notify = false; { const std::scoped_lock guard(lock_); + if (local_participant_) { + local_participant_->markDisconnected(); + } // Local shutdown marks the state before awaiting the FFI response // and notifies the delegate itself. Suppress that duplicate while // passing server-initiated disconnects through unchanged. @@ -1298,115 +1326,12 @@ void Room::onEvent(const FfiEvent& event) { // Deprecated event, do nothing. break; } - case proto::RoomEvent::kStreamHeaderReceived: { - const auto& sh = re.stream_header_received(); - const auto& header = sh.header(); - const std::string& participant_identity = sh.participant_identity(); - - // Snapshot handler + create reader without holding lock during user - // callback - TextStreamHandler text_cb; - ByteStreamHandler byte_cb; - std::shared_ptr text_reader; - std::shared_ptr byte_reader; - { - const std::scoped_lock guard(lock_); - - // Determine stream type from oneof in protobuf - // Adjust these names if your generated C++ uses different ones - const auto stream_type = header.content_header_case(); - if (stream_type == proto::DataStream::Header::kTextHeader) { - auto it = text_stream_handlers_.find(header.topic()); - if (it == text_stream_handlers_.end()) { - // Ignore if no callback attached - break; - } - text_cb = it->second; - - const TextStreamInfo info = makeTextInfo(header); - text_reader = std::make_shared(info); - text_stream_readers_[header.stream_id()] = text_reader; - - } else if (stream_type == proto::DataStream::Header::kByteHeader) { - auto it = byte_stream_handlers_.find(header.topic()); - if (it == byte_stream_handlers_.end()) { - break; - } - byte_cb = it->second; - const ByteStreamInfo info = makeByteInfo(header); - byte_reader = std::make_shared(info); - byte_stream_readers_[header.stream_id()] = byte_reader; - - } else { - // unknown header type: ignore - break; - } - } - - // Invoke user callback outside lock (very important) - if (text_reader) { - text_cb(text_reader, participant_identity); - } else if (byte_reader) { - byte_cb(byte_reader, participant_identity); - } - break; - } - case proto::RoomEvent::kStreamChunkReceived: { - const auto& sc = re.stream_chunk_received(); - const auto& chunk = sc.chunk(); - std::shared_ptr text_reader; - std::shared_ptr byte_reader; - { - const std::scoped_lock guard(lock_); - auto itT = text_stream_readers_.find(chunk.stream_id()); - if (itT != text_stream_readers_.end()) { - text_reader = itT->second; - } else { - auto itB = byte_stream_readers_.find(chunk.stream_id()); - if (itB != byte_stream_readers_.end()) { - byte_reader = itB->second; - } - } - } - if (text_reader) { - // chunk.content() is bytes; treat as UTF-8 string. - text_reader->onChunkUpdate(chunk.content()); - } else if (byte_reader) { - // Convert string bytes -> vector - const std::string& s = chunk.content(); - const std::vector bytes(s.begin(), s.end()); - byte_reader->onChunkUpdate(bytes); - } - break; - } + case proto::RoomEvent::kStreamHeaderReceived: + case proto::RoomEvent::kStreamChunkReceived: case proto::RoomEvent::kStreamTrailerReceived: { - const auto& st = re.stream_trailer_received(); - const auto& trailer = st.trailer(); - std::shared_ptr text_reader; - std::shared_ptr byte_reader; - std::map trailer_attrs; - for (const auto& kv : trailer.attributes()) { - trailer_attrs.emplace(kv.first, kv.second); - } - { - const std::scoped_lock guard(lock_); - auto itT = text_stream_readers_.find(trailer.stream_id()); - if (itT != text_stream_readers_.end()) { - text_reader = itT->second; - text_stream_readers_.erase(itT); - } else { - auto itB = byte_stream_readers_.find(trailer.stream_id()); - if (itB != byte_stream_readers_.end()) { - byte_reader = itB->second; - byte_stream_readers_.erase(itB); - } - } - } - if (text_reader) { - text_reader->onStreamClose(trailer_attrs); - } else if (byte_reader) { - byte_reader->onStreamClose(trailer_attrs); - } + // Low-level packet events. Every stream is also delivered as a + // text/byte_stream_opened event with an owned reader, which is what + // the SDK consumes; handling these too would duplicate streams. break; } case proto::RoomEvent::kDataChannelLowThresholdChanged: { @@ -1417,17 +1342,11 @@ void Room::onEvent(const FfiEvent& event) { break; } case proto::RoomEvent::kByteStreamOpened: { - auto ev = fromProto(re.byte_stream_opened()); - if (delegate_snapshot) { - delegate_snapshot->onByteStreamOpened(*this, ev); - } + onByteStreamOpened(re.byte_stream_opened(), delegate_snapshot); break; } case proto::RoomEvent::kTextStreamOpened: { - auto ev = fromProto(re.text_stream_opened()); - if (delegate_snapshot) { - delegate_snapshot->onTextStreamOpened(*this, ev); - } + onTextStreamOpened(re.text_stream_opened(), delegate_snapshot); break; } case proto::RoomEvent::kRoomUpdated: { @@ -1500,4 +1419,166 @@ void Room::onEvent(const FfiEvent& event) { } } +// ------------------------------------------------------------------- +// Data streams +// ------------------------------------------------------------------- + +void Room::endStreamReaders(const TextStreamReaderMap& text_readers, const ByteStreamReaderMap& byte_readers) { + for (const auto& kv : text_readers) { + kv.second->onStreamEnded({}, std::string(kDisconnectedWhileReceiving)); + } + for (const auto& kv : byte_readers) { + kv.second->onStreamEnded({}, std::string(kDisconnectedWhileReceiving)); + } +} + +bool Room::dispatchStreamReaderEvent(const FfiEvent& event) { + if (event.message_case() == FfiEvent::kTextStreamReaderEvent) { + const auto& ev = event.text_stream_reader_event(); + std::shared_ptr reader; + { + const std::scoped_lock guard(lock_); + const auto it = text_stream_readers_.find(ev.reader_handle()); + if (it == text_stream_readers_.end()) { + return true; // Not ours (another room) or already ended. + } + reader = it->second; + if (ev.has_eos()) { + text_stream_readers_.erase(it); + } + } + if (ev.has_chunk_received()) { + reader->onChunkReceived(ev.chunk_received().content()); + } else if (ev.has_eos()) { + const auto& eos = ev.eos(); + reader->onStreamEnded(toStdMap(eos.attributes()), + eos.has_error() ? std::optional(eos.error().description()) : std::nullopt); + } + return true; + } + + if (event.message_case() == FfiEvent::kByteStreamReaderEvent) { + const auto& ev = event.byte_stream_reader_event(); + std::shared_ptr reader; + { + const std::scoped_lock guard(lock_); + const auto it = byte_stream_readers_.find(ev.reader_handle()); + if (it == byte_stream_readers_.end()) { + return true; + } + reader = it->second; + if (ev.has_eos()) { + byte_stream_readers_.erase(it); + } + } + if (ev.has_chunk_received()) { + const std::string& content = ev.chunk_received().content(); + reader->onChunkReceived(std::vector(content.begin(), content.end())); + } else if (ev.has_eos()) { + const auto& eos = ev.eos(); + reader->onStreamEnded(toStdMap(eos.attributes()), + eos.has_error() ? std::optional(eos.error().description()) : std::nullopt); + } + return true; + } + + return false; +} + +void Room::onTextStreamOpened(const proto::TextStreamOpened& opened, RoomDelegate* delegate) { + const auto& owned = opened.reader(); + const auto reader_handle = static_cast(owned.handle().id()); + + TextStreamHandler handler; + std::shared_ptr reader; + { + const std::scoped_lock guard(lock_); + const auto it = text_stream_handlers_.find(owned.info().topic()); + // room_handle_ is cleared by shutdown(); a stream opened concurrently + // with shutdown is dropped rather than tracked by a dead room. + if (room_handle_ && it != text_stream_handlers_.end()) { + handler = it->second; + reader = std::make_shared(fromProto(owned.info())); + // Register before read_incremental so no chunk can arrive unrouted. + text_stream_readers_[reader_handle] = reader; + } + } + + if (!reader) { + // Nobody will read it: drop the handle so the FFI frees the stream. + const FfiHandle unread(static_cast(reader_handle)); + LK_LOG_DEBUG("No text stream handler for topic '{}'; ignoring stream {}", owned.info().topic(), + owned.info().stream_id()); + } else { + try { + FfiClient::instance().textStreamReadIncremental(reader_handle); + } catch (const std::exception& e) { + LK_LOG_ERROR("Failed to start reading text stream {}: {}", owned.info().stream_id(), e.what()); + { + const std::scoped_lock guard(lock_); + text_stream_readers_.erase(reader_handle); + } + const FfiHandle unread(static_cast(reader_handle)); + reader->onStreamEnded({}, std::string(e.what())); + } + } + + if (reader) { + handler(reader, opened.participant_identity()); + } + + if (delegate) { + const TextStreamOpenedEvent ev = fromProto(opened); + delegate->onTextStreamOpened(*this, ev); + } +} + +void Room::onByteStreamOpened(const proto::ByteStreamOpened& opened, RoomDelegate* delegate) { + const auto& owned = opened.reader(); + const auto reader_handle = static_cast(owned.handle().id()); + + ByteStreamHandler handler; + std::shared_ptr reader; + { + const std::scoped_lock guard(lock_); + const auto it = byte_stream_handlers_.find(owned.info().topic()); + // room_handle_ is cleared by shutdown(); a stream opened concurrently + // with shutdown is dropped rather than tracked by a dead room. + if (room_handle_ && it != byte_stream_handlers_.end()) { + handler = it->second; + reader = std::make_shared(fromProto(owned.info())); + // Register before read_incremental so no chunk can arrive unrouted. + byte_stream_readers_[reader_handle] = reader; + } + } + + if (!reader) { + // Nobody will read it: drop the handle so the FFI frees the stream. + const FfiHandle unread(static_cast(reader_handle)); + LK_LOG_DEBUG("No byte stream handler for topic '{}'; ignoring stream {}", owned.info().topic(), + owned.info().stream_id()); + } else { + try { + FfiClient::instance().byteStreamReadIncremental(reader_handle); + } catch (const std::exception& e) { + LK_LOG_ERROR("Failed to start reading byte stream {}: {}", owned.info().stream_id(), e.what()); + { + const std::scoped_lock guard(lock_); + byte_stream_readers_.erase(reader_handle); + } + const FfiHandle unread(static_cast(reader_handle)); + reader->onStreamEnded({}, std::string(e.what())); + } + } + + if (reader) { + handler(reader, opened.participant_identity()); + } + + if (delegate) { + const ByteStreamOpenedEvent ev = fromProto(opened); + delegate->onByteStreamOpened(*this, ev); + } +} + } // namespace livekit diff --git a/src/room_proto_converter.cpp b/src/room_proto_converter.cpp index 3d543756..b72710fe 100644 --- a/src/room_proto_converter.cpp +++ b/src/room_proto_converter.cpp @@ -381,16 +381,16 @@ DataChannelBufferedAmountLowThresholdChangedEvent fromProto( ByteStreamOpenedEvent fromProto(const proto::ByteStreamOpened& in) { ByteStreamOpenedEvent ev; - // TODO: map reader handle once OwnedByteStreamReader is known - // ev.reader_handle = in.reader().handle().id(); + // reader_handle is intentionally left 0: the Room's ByteStreamReader owns + // and consumes the handle. ev.participant_identity = in.participant_identity(); return ev; } TextStreamOpenedEvent fromProto(const proto::TextStreamOpened& in) { TextStreamOpenedEvent ev; - // TODO: map reader handle once OwnedTextStreamReader is known - // ev.reader_handle = in.reader().handle().id(); + // reader_handle is intentionally left 0: the Room's TextStreamReader owns + // and consumes the handle. ev.participant_identity = in.participant_identity(); return ev; } @@ -472,6 +472,9 @@ proto::RoomOptions toProto(const RoomOptions& in) { if (in.other_sdks) { out.set_other_sdks(*in.other_sdks); } + if (in.data_stream.max_payload_byte_length) { + out.mutable_data_stream()->set_max_payload_byte_length(*in.data_stream.max_payload_byte_length); + } return out; } diff --git a/src/tests/integration/test_data_streams.cpp b/src/tests/integration/test_data_streams.cpp index 2a919ff8..2d73e7c3 100644 --- a/src/tests/integration/test_data_streams.cpp +++ b/src/tests/integration/test_data_streams.cpp @@ -15,20 +15,27 @@ */ // End-to-end coverage for text/byte data streams (registerTextStreamHandler / -// registerByteStreamHandler + TextStreamWriter / ByteStreamWriter). Requires a -// local SFU; see test_data_track.cpp for setup instructions. Run with: +// registerByteStreamHandler + LocalParticipant::sendText / sendBytes / sendFile +// and TextStreamWriter / ByteStreamWriter). Requires a local SFU; see +// test_data_track.cpp for setup instructions. Run with: // ./build-debug/bin/livekit_integration_tests --gtest_filter=*DataStream* #include +#include #include #include +#include +#include #include +#include #include #include #include #include "../common/test_common.h" +#include "ffi.pb.h" +#include "ffi_client.h" namespace livekit::test { @@ -47,6 +54,14 @@ std::string makeTopic(const std::string& suffix) { class TextStreamCollector { public: ~TextStreamCollector() { + // If the test failed before the stream ended, wake the reader so joining + // doesn't hang the test binary. + std::unique_lock lock(mutex_); + auto reader = reader_.lock(); + lock.unlock(); + if (reader) { + reader->close(); + } if (recv_thread_.joinable()) { recv_thread_.join(); } @@ -58,12 +73,23 @@ class TextStreamCollector { // until close, so it has to happen on a separate thread. room.registerTextStreamHandler( topic, [this](std::shared_ptr reader, const std::string& participant_identity) { + { + std::lock_guard lock(mutex_); + reader_ = reader; + } recv_thread_ = std::thread([this, reader, participant_identity] { - auto info = reader->info(); - auto text = reader->readAll(); + std::string text; + std::optional error; + try { + text = reader->readAll(); + } catch (const DataStreamError& e) { + error = e.what(); + } std::lock_guard lock(mutex_); - info_ = std::move(info); + // Read info after the stream ends so trailer attributes are merged. + info_ = reader->info(); text_ = std::move(text); + error_ = std::move(error); sender_identity_ = participant_identity; done_ = true; cv_.notify_all(); @@ -78,15 +104,18 @@ class TextStreamCollector { const TextStreamInfo& info() const { return info_; } const std::string& text() const { return text_; } + const std::optional& error() const { return error_; } const std::string& senderIdentity() const { return sender_identity_; } private: + std::weak_ptr reader_; std::thread recv_thread_; std::mutex mutex_; std::condition_variable cv_; bool done_ = false; TextStreamInfo info_; std::string text_; + std::optional error_; std::string sender_identity_; }; @@ -94,6 +123,14 @@ class TextStreamCollector { class ByteStreamCollector { public: ~ByteStreamCollector() { + // If the test failed before the stream ended, wake the reader so joining + // doesn't hang the test binary. + std::unique_lock lock(mutex_); + auto reader = reader_.lock(); + lock.unlock(); + if (reader) { + reader->close(); + } if (recv_thread_.joinable()) { recv_thread_.join(); } @@ -103,16 +140,25 @@ class ByteStreamCollector { // not run on the Room event thread. room.registerByteStreamHandler( topic, [this](std::shared_ptr reader, const std::string& participant_identity) { + { + std::lock_guard lock(mutex_); + reader_ = reader; + } recv_thread_ = std::thread([this, reader, participant_identity] { - auto info = reader->info(); std::vector content; std::vector chunk; - while (reader->readNext(chunk)) { - content.insert(content.end(), chunk.begin(), chunk.end()); + std::optional error; + try { + while (reader->readNext(chunk)) { + content.insert(content.end(), chunk.begin(), chunk.end()); + } + } catch (const DataStreamError& e) { + error = e.what(); } std::lock_guard lock(mutex_); - info_ = std::move(info); + info_ = reader->info(); content_ = std::move(content); + error_ = std::move(error); sender_identity_ = participant_identity; done_ = true; cv_.notify_all(); @@ -127,18 +173,85 @@ class ByteStreamCollector { const ByteStreamInfo& info() const { return info_; } const std::vector& content() const { return content_; } + const std::optional& error() const { return error_; } const std::string& senderIdentity() const { return sender_identity_; } private: + std::weak_ptr reader_; std::thread recv_thread_; std::mutex mutex_; std::condition_variable cv_; bool done_ = false; ByteStreamInfo info_; std::vector content_; + std::optional error_; std::string sender_identity_; }; +/// Text that compresses well, cycling through ASCII letters. +std::string compressibleText(std::size_t size) { + std::string out; + out.reserve(size); + for (std::size_t i = 0; i < size; ++i) { + out.push_back(static_cast('a' + (i % 26))); + } + return out; +} + +/// Multi-byte UTF-8 text (2-, 3- and 4-byte code points) of at least @p size bytes. +std::string unicodeText(std::size_t size) { + const std::string unit = "h\xC3\xA9llo \xE4\xB8\x96\xE7\x95\x8C \xF0\x9F\x91\x8B "; + std::string out; + while (out.size() < size) { + out += unit; + } + return out; +} + +/// Records the reader handle of every opened data stream, to probe whether the +/// SDK released them. +class OpenedStreamHandleRecorder { +public: + OpenedStreamHandleRecorder() { + listener_id_ = FfiClient::instance().addListener([this](const proto::FfiEvent& event) { + if (event.message_case() != proto::FfiEvent::kRoomEvent) { + return; + } + const auto& re = event.room_event(); + std::uint64_t handle = 0; + if (re.has_text_stream_opened()) { + handle = re.text_stream_opened().reader().handle().id(); + } else if (re.has_byte_stream_opened()) { + handle = re.byte_stream_opened().reader().handle().id(); + } else { + return; + } + std::lock_guard lock(mutex_); + handles_.push_back(handle); + cv_.notify_all(); + }); + } + ~OpenedStreamHandleRecorder() { FfiClient::instance().removeListener(listener_id_); } + OpenedStreamHandleRecorder(const OpenedStreamHandleRecorder&) = delete; + OpenedStreamHandleRecorder& operator=(const OpenedStreamHandleRecorder&) = delete; + + bool waitForCount(std::size_t count, std::chrono::milliseconds timeout) { + std::unique_lock lock(mutex_); + return cv_.wait_for(lock, timeout, [this, count] { return handles_.size() >= count; }); + } + + std::vector handles() { + std::lock_guard lock(mutex_); + return handles_; + } + +private: + FfiClient::ListenerId listener_id_ = 0; + std::mutex mutex_; + std::condition_variable cv_; + std::vector handles_; +}; + } // namespace class DataStreamE2ETest : public LiveKitTestBase {}; @@ -218,4 +331,308 @@ TEST_F(DataStreamE2ETest, ByteStreamRoundTripEndToEnd) { EXPECT_EQ(collector.info().name, "payload.bin"); } +// --------------------------------------------------------------------------- +// One-shot sends (sendText / sendBytes / sendFile). These produce data streams +// v2 traffic (single-packet and compressed), like every other LiveKit SDK. +// --------------------------------------------------------------------------- + +TEST_F(DataStreamE2ETest, SendTextSmallRoundTrip) { + const auto topic = makeTopic("send_text_small"); + auto rooms = testRooms(2); + auto sender = lockLocalParticipant(*rooms[0]); + + TextStreamCollector collector; + collector.registerOn(*rooms[1], topic); + + StreamTextOptions options; + options.topic = topic; + options.attributes = {{"kind", "greeting"}}; + const auto sent = sender->sendText("hi there", options); + EXPECT_FALSE(sent.stream_id.empty()); + EXPECT_EQ(sent.topic, topic); + + ASSERT_TRUE(collector.wait(kStreamWaitTimeout)) << "Timed out waiting for text stream"; + EXPECT_FALSE(collector.error().has_value()) << *collector.error(); + EXPECT_EQ(collector.text(), "hi there"); + EXPECT_EQ(collector.info().stream_id, sent.stream_id); + EXPECT_EQ(collector.info().mime_type, "text/plain"); + EXPECT_EQ(collector.info().attributes.at("kind"), "greeting"); + EXPECT_EQ(collector.senderIdentity(), sender->identity()); +} + +TEST_F(DataStreamE2ETest, SendTextLargeCompressedRoundTrip) { + const auto topic = makeTopic("send_text_large"); + const auto payload = compressibleText(50 * 1024); + auto rooms = testRooms(2); + + TextStreamCollector collector; + collector.registerOn(*rooms[1], topic); + + StreamTextOptions options; + options.topic = topic; + (void)lockLocalParticipant(*rooms[0])->sendText(payload, options); + + ASSERT_TRUE(collector.wait(kStreamWaitTimeout)) << "Timed out waiting for text stream"; + EXPECT_FALSE(collector.error().has_value()) << *collector.error(); + EXPECT_EQ(collector.text(), payload); +} + +TEST_F(DataStreamE2ETest, SendTextUncompressedRoundTrip) { + const auto topic = makeTopic("send_text_uncompressed"); + const auto payload = compressibleText(50 * 1024); + auto rooms = testRooms(2); + + TextStreamCollector collector; + collector.registerOn(*rooms[1], topic); + + StreamTextOptions options; + options.topic = topic; + options.compress = false; + (void)lockLocalParticipant(*rooms[0])->sendText(payload, options); + + ASSERT_TRUE(collector.wait(kStreamWaitTimeout)) << "Timed out waiting for text stream"; + EXPECT_FALSE(collector.error().has_value()) << *collector.error(); + EXPECT_EQ(collector.text(), payload); +} + +TEST_F(DataStreamE2ETest, SendTextUnicodeRoundTrip) { + const auto topic = makeTopic("send_text_unicode"); + // Larger than one 15 KB chunk, uncompressed, so multi-byte code points + // straddle chunk boundaries. + const auto payload = unicodeText(40 * 1024); + auto rooms = testRooms(2); + + TextStreamCollector collector; + collector.registerOn(*rooms[1], topic); + + StreamTextOptions options; + options.topic = topic; + options.compress = false; + (void)lockLocalParticipant(*rooms[0])->sendText(payload, options); + + ASSERT_TRUE(collector.wait(kStreamWaitTimeout)) << "Timed out waiting for text stream"; + EXPECT_FALSE(collector.error().has_value()) << *collector.error(); + EXPECT_EQ(collector.text(), payload); +} + +TEST_F(DataStreamE2ETest, SendBytesSmallRoundTrip) { + const auto topic = makeTopic("send_bytes"); + const std::vector payload{0x00, 0x01, 0xFE, 0xFF, 'o', 'k'}; + auto rooms = testRooms(2); + + ByteStreamCollector collector; + collector.registerOn(*rooms[1], topic); + + StreamByteOptions options; + options.topic = topic; + options.name = "blob.bin"; + options.mime_type = "application/x-test"; + const auto sent = lockLocalParticipant(*rooms[0])->sendBytes(payload, options); + + ASSERT_TRUE(collector.wait(kStreamWaitTimeout)) << "Timed out waiting for byte stream"; + EXPECT_FALSE(collector.error().has_value()) << *collector.error(); + EXPECT_EQ(collector.content(), payload); + EXPECT_EQ(collector.info().stream_id, sent.stream_id); + EXPECT_EQ(collector.info().name, "blob.bin"); + EXPECT_EQ(collector.info().mime_type, "application/x-test"); +} + +TEST_F(DataStreamE2ETest, SendFileRoundTrip) { + const auto topic = makeTopic("send_file"); + const std::string file_name = "lk_send_file_" + std::to_string(getTimestampUs()) + ".txt"; + const std::string path = ::testing::TempDir() + file_name; + const auto payload = compressibleText(20 * 1024); + { + std::ofstream out(path, std::ios::binary); + out << payload; + } + auto rooms = testRooms(2); + + ByteStreamCollector collector; + collector.registerOn(*rooms[1], topic); + + StreamByteOptions options; + options.topic = topic; + const auto sent = lockLocalParticipant(*rooms[0])->sendFile(path, options); + EXPECT_EQ(sent.name, file_name) << "name defaults to the file's basename"; + EXPECT_FALSE(sent.mime_type.empty()); + + ASSERT_TRUE(collector.wait(kStreamWaitTimeout)) << "Timed out waiting for file stream"; + std::remove(path.c_str()); + EXPECT_FALSE(collector.error().has_value()) << *collector.error(); + EXPECT_EQ(std::string(collector.content().begin(), collector.content().end()), payload); + EXPECT_EQ(collector.info().name, file_name); + EXPECT_EQ(collector.info().mime_type, sent.mime_type); +} + +TEST_F(DataStreamE2ETest, SendFileMissingFileThrows) { + auto rooms = testRooms(1); + StreamByteOptions options; + options.topic = makeTopic("send_file_missing"); + EXPECT_THROW((void)lockLocalParticipant(*rooms[0])->sendFile(::testing::TempDir() + "no-such-file.bin", options), + DataStreamError); +} + +TEST_F(DataStreamE2ETest, SendAfterDisconnectThrows) { + auto rooms = testRooms(1); + auto sender = lockLocalParticipant(*rooms[0]); + ASSERT_TRUE(rooms[0]->disconnect()); + + StreamTextOptions text_options; + text_options.topic = makeTopic("after_disconnect"); + StreamByteOptions byte_options; + byte_options.topic = text_options.topic; + EXPECT_THROW((void)sender->sendText("late", text_options), DataStreamError); + EXPECT_THROW((void)sender->sendBytes({1}, byte_options), DataStreamError); +} + +// --------------------------------------------------------------------------- +// Receive-side behaviour +// --------------------------------------------------------------------------- + +TEST_F(DataStreamE2ETest, ReceiveSizeLimitEndsStreamWithError) { + const auto topic = makeTopic("size_limit"); + std::vector configs(2); + configs[1].room_options.data_stream.max_payload_byte_length = 1000; + auto rooms = testRooms(configs); + + TextStreamCollector collector; + collector.registerOn(*rooms[1], topic); + + StreamTextOptions options; + options.topic = topic; + (void)lockLocalParticipant(*rooms[0])->sendText(compressibleText(50 * 1024), options); + + ASSERT_TRUE(collector.wait(kStreamWaitTimeout)) << "Timed out waiting for text stream"; + ASSERT_TRUE(collector.error().has_value()) << "an oversized stream must surface an error"; + EXPECT_NE(collector.error()->find("payload exceeds maximum size"), std::string::npos) << *collector.error(); +} + +TEST_F(DataStreamE2ETest, TrailerAttributesAreMergedIntoInfo) { + const auto topic = makeTopic("trailer_attrs"); + auto rooms = testRooms(2); + + TextStreamCollector collector; + collector.registerOn(*rooms[1], topic); + + TextStreamWriter writer(*lockLocalParticipant(*rooms[0]), topic, {{"header_key", "h"}}); + writer.write("body"); + writer.close("", {{"trailer_key", "t"}}); + + ASSERT_TRUE(collector.wait(kStreamWaitTimeout)) << "Timed out waiting for text stream"; + EXPECT_FALSE(collector.error().has_value()) << *collector.error(); + EXPECT_EQ(collector.text(), "body"); + EXPECT_EQ(collector.info().attributes.at("header_key"), "h"); + EXPECT_EQ(collector.info().attributes.at("trailer_key"), "t"); +} + +TEST_F(DataStreamE2ETest, AbnormalCloseSurfacesError) { + const auto topic = makeTopic("abnormal_close"); + auto rooms = testRooms(2); + + ByteStreamCollector collector; + collector.registerOn(*rooms[1], topic); + + ByteStreamWriter writer(*lockLocalParticipant(*rooms[0]), "partial.bin", topic); + writer.write({1, 2, 3}); + writer.close("boom"); + + ASSERT_TRUE(collector.wait(kStreamWaitTimeout)) << "Timed out waiting for byte stream"; + ASSERT_TRUE(collector.error().has_value()) << "a close with a reason must surface an error"; + EXPECT_NE(collector.error()->find("boom"), std::string::npos) << *collector.error(); + EXPECT_EQ(collector.content(), (std::vector{1, 2, 3})); +} + +TEST_F(DataStreamE2ETest, ReceiverDisconnectMidStreamWakesReader) { + const auto topic = makeTopic("receiver_disconnect"); + auto rooms = testRooms(2); + + TextStreamCollector collector; + collector.registerOn(*rooms[1], topic); + + TextStreamWriter writer(*lockLocalParticipant(*rooms[0]), topic); + writer.write("first part"); + // Give the receiver time to open the reader and block on the next chunk. + std::this_thread::sleep_for(1s); + ASSERT_TRUE(rooms[1]->disconnect()); + + ASSERT_TRUE(collector.wait(kStreamWaitTimeout)) << "A blocked reader must wake when its room disconnects"; + EXPECT_TRUE(collector.error().has_value()) << "an interrupted stream must surface an error"; + writer.close(); +} + +TEST_F(DataStreamE2ETest, ReaderCloseWakesPendingRead) { + const auto topic = makeTopic("reader_close"); + auto rooms = testRooms(2); + + std::mutex mutex; + std::condition_variable cv; + std::shared_ptr reader; + rooms[1]->registerTextStreamHandler(topic, [&](std::shared_ptr r, const std::string&) { + std::lock_guard lock(mutex); + reader = std::move(r); + cv.notify_all(); + }); + + TextStreamWriter writer(*lockLocalParticipant(*rooms[0]), topic); + writer.write("first"); + { + std::unique_lock lock(mutex); + ASSERT_TRUE(cv.wait_for(lock, kStreamWaitTimeout, [&] { return reader != nullptr; })); + } + + std::atomic chunks{0}; + std::atomic finished{false}; + std::thread read_thread([&] { + std::string chunk; + while (reader->readNext(chunk)) { + ++chunks; + } + finished = true; + }); + + std::this_thread::sleep_for(500ms); + EXPECT_FALSE(finished) << "reader should still be waiting for more data"; + reader->close(); + read_thread.join(); + EXPECT_TRUE(finished); + EXPECT_EQ(chunks.load(), 1); + writer.close(); +} + +TEST_F(DataStreamE2ETest, StreamHandlesAreReleased) { + const auto handled_topic = makeTopic("handled"); + const auto unhandled_topic = makeTopic("unhandled"); + constexpr std::size_t kUnhandledStreams = 20; + + auto rooms = testRooms(2); + auto sender = lockLocalParticipant(*rooms[0]); + // Only count streams that reach the receiver room. + OpenedStreamHandleRecorder recorder; + + TextStreamCollector collector; + collector.registerOn(*rooms[1], handled_topic); + + StreamTextOptions unhandled; + unhandled.topic = unhandled_topic; + for (std::size_t i = 0; i < kUnhandledStreams; ++i) { + (void)sender->sendText("nobody listens " + std::to_string(i), unhandled); + } + StreamTextOptions handled; + handled.topic = handled_topic; + (void)sender->sendText("somebody listens", handled); + + ASSERT_TRUE(collector.wait(kStreamWaitTimeout)); + ASSERT_TRUE(recorder.waitForCount(kUnhandledStreams + 1, kStreamWaitTimeout)); + // The Room handles each opened event in the same callback that the recorder + // sees; allow a moment for the last one to finish. + std::this_thread::sleep_for(200ms); + + // Dropping a handle that the SDK already released (unhandled topic) or + // consumed (read) reports that it no longer exists. + for (const auto handle : recorder.handles()) { + EXPECT_FALSE(dropFfiHandle(handle)) << "reader handle " << handle << " was leaked"; + } +} + } // namespace livekit::test diff --git a/src/tests/unit/test_data_stream.cpp b/src/tests/unit/test_data_stream.cpp index 840f5e02..c399e422 100644 --- a/src/tests/unit/test_data_stream.cpp +++ b/src/tests/unit/test_data_stream.cpp @@ -16,11 +16,54 @@ #include #include +#include +#include +#include +#include +#include #include +#include "data_stream_proto_converter.h" +#include "ffi_client.h" +#include "room_proto_converter.h" + +namespace livekit { + +/// Feeds synthetic FFI reader events into detached readers. +struct DataStreamReaderTestAccess { + static void chunk(TextStreamReader& reader, std::string text) { reader.onChunkReceived(std::move(text)); } + static void chunk(ByteStreamReader& reader, std::vector bytes) { + reader.onChunkReceived(std::move(bytes)); + } + template + static void end(Reader& reader, const std::map& attributes = {}, + std::optional error = std::nullopt) { + reader.onStreamEnded(attributes, std::move(error)); + } +}; + +} // namespace livekit + namespace livekit::test { +using namespace std::chrono_literals; +using Access = DataStreamReaderTestAccess; + +namespace { + +// The proto is built inside liblivekit, which carries its own protobuf copy +// with a different hash seed; iterate instead of using Map::at() / find(). +std::map attrs(const google::protobuf::Map& in) { + std::map out; + for (const auto& kv : in) { + out.emplace(kv.first, kv.second); + } + return out; +} + +} // namespace + TEST(DataStreamTest, TextStreamReaderConstructAndInfo) { TextStreamInfo info; info.stream_id = "stream-1"; @@ -56,4 +99,268 @@ TEST(DataStreamTest, WriterTypesAreDerivedFromBase) { EXPECT_GT(kStreamChunkSize, 0u); } +// --------------------------------------------------------------------------- +// Reader state machine (detached readers fed synthetic events) +// --------------------------------------------------------------------------- + +TEST(DataStreamReaderTest, TextReaderDeliversChunksThenEnds) { + TextStreamReader reader(TextStreamInfo{}); + Access::chunk(reader, "hello, "); + Access::chunk(reader, "world"); + Access::end(reader); + EXPECT_EQ(reader.readAll(), "hello, world"); + + std::string out; + EXPECT_FALSE(reader.readNext(out)) << "readNext after the end keeps returning false"; +} + +TEST(DataStreamReaderTest, ByteReaderReadAllConcatenates) { + ByteStreamReader reader(ByteStreamInfo{}); + Access::chunk(reader, std::vector{1, 2}); + Access::chunk(reader, std::vector{3}); + Access::end(reader); + EXPECT_EQ(reader.readAll(), (std::vector{1, 2, 3})); +} + +TEST(DataStreamReaderTest, EndAttributesAreMergedAfterEnd) { + TextStreamInfo info; + info.attributes = {{"header", "h"}, {"shared", "old"}}; + TextStreamReader reader(info); + Access::chunk(reader, "x"); + Access::end(reader, {{"trailer", "t"}, {"shared", "new"}}); + + std::string out; + ASSERT_TRUE(reader.readNext(out)); + EXPECT_EQ(reader.info().attributes.count("trailer"), 0u) << "attributes are merged only once the end is reached"; + EXPECT_FALSE(reader.readNext(out)); + EXPECT_EQ(reader.info().attributes.at("header"), "h"); + EXPECT_EQ(reader.info().attributes.at("trailer"), "t"); + EXPECT_EQ(reader.info().attributes.at("shared"), "new"); +} + +TEST(DataStreamReaderTest, ErrorIsThrownAfterBufferedChunks) { + ByteStreamReader reader(ByteStreamInfo{}); + Access::chunk(reader, std::vector{42}); + Access::end(reader, {}, std::string("stream closed abnormally: boom")); + + std::vector out; + ASSERT_TRUE(reader.readNext(out)); + EXPECT_EQ(out, std::vector{42}); + try { + (void)reader.readNext(out); + FAIL() << "expected DataStreamError"; + } catch (const DataStreamError& e) { + EXPECT_NE(std::string(e.what()).find("boom"), std::string::npos); + } + EXPECT_THROW((void)reader.readNext(out), DataStreamError) << "the error is sticky"; +} + +TEST(DataStreamReaderTest, ReadAllThrowsOnError) { + TextStreamReader reader(TextStreamInfo{}); + Access::chunk(reader, "partial"); + Access::end(reader, {}, std::string("Disconnected while receiving")); + EXPECT_THROW((void)reader.readAll(), DataStreamError); +} + +TEST(DataStreamReaderTest, DataStreamErrorIsARuntimeError) { + TextStreamReader reader(TextStreamInfo{}); + Access::end(reader, {}, std::string("boom")); + EXPECT_THROW((void)reader.readAll(), std::runtime_error); +} + +TEST(DataStreamReaderTest, CloseWakesBlockedRead) { + auto reader = std::make_shared(TextStreamInfo{}); + auto result = std::async(std::launch::async, [reader] { + std::string out; + return reader->readNext(out); + }); + EXPECT_EQ(result.wait_for(100ms), std::future_status::timeout) << "readNext should block with no data"; + + reader->close(); + ASSERT_EQ(result.wait_for(5s), std::future_status::ready); + EXPECT_FALSE(result.get()); +} + +TEST(DataStreamReaderTest, CloseDiscardsBufferedDataAndIsIdempotent) { + ByteStreamReader reader(ByteStreamInfo{}); + Access::chunk(reader, std::vector{1}); + reader.close(); + reader.close(); + Access::chunk(reader, std::vector{2}); + Access::end(reader, {}, std::string("ignored after close")); + + std::vector out; + EXPECT_FALSE(reader.readNext(out)); + EXPECT_TRUE(reader.readAll().empty()); +} + +TEST(DataStreamReaderTest, TerminalErrorWakesBlockedRead) { + auto reader = std::make_shared(ByteStreamInfo{}); + auto result = std::async(std::launch::async, [reader] { return reader->readAll(); }); + EXPECT_EQ(result.wait_for(100ms), std::future_status::timeout); + + Access::end(*reader, {}, std::string("Disconnected while receiving")); + ASSERT_EQ(result.wait_for(5s), std::future_status::ready); + EXPECT_THROW((void)result.get(), DataStreamError); +} + +// --------------------------------------------------------------------------- +// Option / info conversion +// --------------------------------------------------------------------------- + +TEST(DataStreamConversionTest, TextOptionsDefaultsToProto) { + StreamTextOptions options; + options.topic = "chat"; + const auto proto = toProto(options); + EXPECT_EQ(proto.topic(), "chat"); + ASSERT_TRUE(proto.has_compress()) << "compress is always sent explicitly"; + EXPECT_TRUE(proto.compress()); + EXPECT_FALSE(proto.has_id()); + EXPECT_FALSE(proto.has_reply_to_stream_id()); + EXPECT_FALSE(proto.has_sender_identity()); + EXPECT_FALSE(proto.has_operation_type()); + EXPECT_EQ(proto.destination_identities_size(), 0); +} + +TEST(DataStreamConversionTest, TextOptionsAllFieldsToProto) { + StreamTextOptions options; + options.topic = "chat"; + options.attributes = {{"k", "v"}}; + options.destination_identities = {"alice", "bob"}; + options.stream_id = "stream-1"; + options.reply_to_stream_id = "stream-0"; + options.attached_stream_ids = {"file-1"}; + options.compress = false; + options.sender_identity = "agent"; + + const auto proto = toProto(options); + EXPECT_EQ(attrs(proto.attributes()), (std::map{{"k", "v"}})); + ASSERT_EQ(proto.destination_identities_size(), 2); + EXPECT_EQ(proto.destination_identities(1), "bob"); + EXPECT_EQ(proto.id(), "stream-1"); + EXPECT_EQ(proto.reply_to_stream_id(), "stream-0"); + ASSERT_EQ(proto.attached_stream_ids_size(), 1); + EXPECT_EQ(proto.attached_stream_ids(0), "file-1"); + ASSERT_TRUE(proto.has_compress()); + EXPECT_FALSE(proto.compress()); + EXPECT_EQ(proto.sender_identity(), "agent"); +} + +TEST(DataStreamConversionTest, ByteOptionsToProto) { + StreamByteOptions defaults; + defaults.topic = "files"; + const auto unset = toProto(defaults); + EXPECT_TRUE(unset.has_compress()); + EXPECT_TRUE(unset.compress()); + EXPECT_FALSE(unset.has_name()); + EXPECT_FALSE(unset.has_mime_type()); + EXPECT_FALSE(unset.has_total_length()); + EXPECT_FALSE(unset.has_id()); + EXPECT_FALSE(unset.has_sender_identity()); + + StreamByteOptions options; + options.topic = "files"; + options.attributes = {{"k", "v"}}; + options.destination_identities = {"alice"}; + options.stream_id = "stream-2"; + options.name = "photo.jpg"; + options.mime_type = "image/jpeg"; + options.total_length = 1234; + options.compress = false; + options.sender_identity = "agent"; + const auto proto = toProto(options); + EXPECT_EQ(proto.topic(), "files"); + EXPECT_EQ(attrs(proto.attributes()), (std::map{{"k", "v"}})); + EXPECT_EQ(proto.destination_identities(0), "alice"); + EXPECT_EQ(proto.id(), "stream-2"); + EXPECT_EQ(proto.name(), "photo.jpg"); + EXPECT_EQ(proto.mime_type(), "image/jpeg"); + EXPECT_EQ(proto.total_length(), 1234u); + EXPECT_FALSE(proto.compress()); + EXPECT_EQ(proto.sender_identity(), "agent"); +} + +TEST(DataStreamConversionTest, TextInfoFromProto) { + proto::TextStreamInfo in; + in.set_stream_id("s1"); + in.set_timestamp(99); + in.set_mime_type("text/plain"); + in.set_topic("chat"); + (*in.mutable_attributes())["k"] = "v"; + in.add_attached_stream_ids("a1"); + in.set_reply_to_stream_id("s0"); + + auto out = fromProto(in); + EXPECT_EQ(out.stream_id, "s1"); + EXPECT_EQ(out.timestamp, 99); + EXPECT_EQ(out.mime_type, "text/plain"); + EXPECT_EQ(out.topic, "chat"); + EXPECT_EQ(out.attributes.at("k"), "v"); + EXPECT_EQ(out.attachments, std::vector{"a1"}); + ASSERT_TRUE(out.reply_to_stream_id.has_value()); + EXPECT_EQ(*out.reply_to_stream_id, "s0"); + EXPECT_FALSE(out.size.has_value()) << "an absent total_length stays unset"; + + in.set_total_length(10); + in.clear_reply_to_stream_id(); + out = fromProto(in); + ASSERT_TRUE(out.size.has_value()); + EXPECT_EQ(*out.size, 10u); + EXPECT_FALSE(out.reply_to_stream_id.has_value()); +} + +TEST(DataStreamConversionTest, ByteInfoFromProto) { + proto::ByteStreamInfo in; + in.set_stream_id("s2"); + in.set_timestamp(5); + in.set_mime_type("image/png"); + in.set_topic("files"); + in.set_name("a.png"); + in.set_total_length(2048); + + const auto out = fromProto(in); + EXPECT_EQ(out.stream_id, "s2"); + EXPECT_EQ(out.mime_type, "image/png"); + EXPECT_EQ(out.topic, "files"); + EXPECT_EQ(out.name, "a.png"); + ASSERT_TRUE(out.size.has_value()); + EXPECT_EQ(*out.size, 2048u); +} + +TEST(DataStreamConversionTest, RoomOptionsDataStreamToProto) { + RoomOptions options; + EXPECT_FALSE(toProto(options).has_data_stream()) << "unset limit leaves the SDK default"; + + options.data_stream.max_payload_byte_length = 1000; + const auto proto = toProto(options); + ASSERT_TRUE(proto.has_data_stream()); + EXPECT_EQ(proto.data_stream().max_payload_byte_length(), 1000u); +} + +// --------------------------------------------------------------------------- +// One-shot sends refuse to reach an uninitialized FFI +// --------------------------------------------------------------------------- + +TEST(DataStreamSendTest, SendsThrowWhenNotInitialized) { + ASSERT_FALSE(FfiClient::instance().isInitialized()); + LocalParticipant participant(FfiHandle(0), "sid", "name", "identity", "", {}, ParticipantKind::Standard, + DisconnectReason::Unknown); + StreamTextOptions text_options; + text_options.topic = "t"; + StreamByteOptions byte_options; + byte_options.topic = "t"; + EXPECT_THROW((void)participant.sendText("hi", text_options), DataStreamError); + EXPECT_THROW((void)participant.sendBytes({1, 2}, byte_options), DataStreamError); + EXPECT_THROW((void)participant.sendFile("/tmp/does-not-matter", byte_options), DataStreamError); +} + +TEST(DataStreamSendTest, FfiHelpersThrowWhenNotInitialized) { + ASSERT_FALSE(FfiClient::instance().isInitialized()); + EXPECT_THROW(FfiClient::instance().sendTextAsync(1, "hi", proto::StreamTextOptions{}), std::runtime_error); + EXPECT_THROW(FfiClient::instance().sendBytesAsync(1, {1}, proto::StreamByteOptions{}), std::runtime_error); + EXPECT_THROW(FfiClient::instance().sendFileAsync(1, "/tmp/x", proto::StreamByteOptions{}), std::runtime_error); + EXPECT_THROW(FfiClient::instance().textStreamReadIncremental(1), std::runtime_error); + EXPECT_THROW(FfiClient::instance().byteStreamReadIncremental(1), std::runtime_error); +} + } // namespace livekit::test