FfiClient state guarding, additional testing coverage (#125)

Author: alan-george-lk

.github/workflows/tests.yml

@@ -345,6 +345,7 @@ jobs:
             --root . \
             --gcov-executable "${GCOV_EXECUTABLE}" \
             --gcov-ignore-parse-errors=all \
+            --filter 'include/' \
             --filter 'src/' \
             --exclude 'src/tests/' \
             --exclude '.*\.pb\.' \

src/ffi_client.cpp

@@ -141,6 +141,11 @@ std::optional<FfiClient::AsyncId> ExtractAsyncId(const proto::FfiEvent& event) {
 
 } // namespace
 
+FfiClient& FfiClient::instance() noexcept {
+  static FfiClient instance;
+  return instance;
+}
+
 // clang-tidy flags this as a trivial destructor in release mode
 // due to the assert being pre-processed out
 // NOLINTNEXTLINE(modernize-use-equals-default)
@@ -182,6 +187,13 @@ void FfiClient::RemoveListener(ListenerId id) {
 }
 
 proto::FfiResponse FfiClient::sendRequest(const proto::FfiRequest& request) const {
+  // The Rust FFI will lazily initialize the FFI client when the first request is sent,
+  // but if not initialized none of the async operations will work. Guarding against that here.
+  // Improvement ticket added to the Rust SDK to discuss this
+  if (!isInitialized()) {
+    throw std::runtime_error("FfiClient::sendRequest failed: LiveKit is not initialized");
+  }
+
   std::string bytes;
   if (!request.SerializeToString(&bytes) || bytes.empty()) {
     throw std::runtime_error("failed to serialize FfiRequest");

src/ffi_client.h

@@ -74,10 +74,9 @@ class LIVEKIT_INTERNAL_API FfiClient {
   FfiClient(FfiClient&&) = delete;
   FfiClient& operator=(FfiClient&&) = delete;
 
-  static FfiClient& instance() noexcept {
-    static FfiClient instance;
-    return instance;
-  }
+  // Access the singleton instance of the FfiClient
+  // Note: lazily created, not thread safe
+  static FfiClient& instance() noexcept;
 
   // Must be called before any other FFI usage
   bool initialize(bool capture_logs);

src/livekit.cpp

@@ -22,14 +22,16 @@
 namespace livekit {
 
 bool initialize(const LogLevel& level, const LogSink& log_sink) {
+  // Initializes logger if singleton instance is not already initialized
   setLogLevel(level);
   auto& ffi_client = FfiClient::instance();
   return ffi_client.initialize(log_sink == LogSink::kCallback);
 }
 
+bool isInitialized() { return FfiClient::instance().isInitialized(); }
+
 void shutdown() {
-  auto& ffi_client = FfiClient::instance();
-  ffi_client.shutdown();
+  FfiClient::instance().shutdown();
   detail::shutdownLogger();
 }
 

src/room.cpp

@@ -23,6 +23,7 @@
 #include "ffi_client.h"
 #include "livekit/audio_stream.h"
 #include "livekit/e2ee.h"
+#include "livekit/livekit.h"
 #include "livekit/local_data_track.h"
 #include "livekit/local_participant.h"
 #include "livekit/local_track_publication.h"
@@ -105,6 +106,11 @@ void Room::setDelegate(RoomDelegate* delegate) {
 bool Room::Connect(const std::string& url, const std::string& token, const RoomOptions& options) {
   TRACE_EVENT0("livekit", "Room::Connect");
 
+  if (!FfiClient::instance().isInitialized()) {
+    LK_LOG_ERROR("Room::Connect failed: LiveKit is not initialized");
+    return false;
+  }
+
   {
     const std::scoped_lock<std::mutex> g(lock_);
     if (connection_state_ != ConnectionState::Disconnected) {

src/tests/integration/test_room.cpp

@@ -19,78 +19,8 @@
 
 namespace livekit::test {
 
-class RoomTest : public ::testing::Test {
-protected:
-  void SetUp() override { livekit::initialize(livekit::LogLevel::Info, livekit::LogSink::kConsole); }
-
-  void TearDown() override { livekit::shutdown(); }
-};
-
-TEST_F(RoomTest, CreateRoom) {
-  Room room;
-  // Room should be created without issues
-  EXPECT_EQ(room.localParticipant(), nullptr) << "Local participant should be null before connect";
-}
-
-TEST_F(RoomTest, RoomOptionsDefaults) {
-  RoomOptions options;
-
-  EXPECT_TRUE(options.auto_subscribe) << "auto_subscribe should default to true";
-  EXPECT_FALSE(options.dynacast) << "dynacast should default to false";
-  EXPECT_FALSE(options.rtc_config.has_value()) << "rtc_config should not have a value by default";
-  EXPECT_FALSE(options.encryption.has_value()) << "encryption should not have a value by default";
-}
-
-TEST_F(RoomTest, RtcConfigDefaults) {
-  RtcConfig config;
-
-  EXPECT_EQ(config.ice_transport_type, 0);
-  EXPECT_EQ(config.continual_gathering_policy, 0);
-  EXPECT_TRUE(config.ice_servers.empty());
-}
-
-TEST_F(RoomTest, IceServerConfiguration) {
-  IceServer server;
-  server.url = "stun:stun.l.google.com:19302";
-  server.username = "user";
-  server.credential = "pass";
-
-  EXPECT_EQ(server.url, "stun:stun.l.google.com:19302");
-  EXPECT_EQ(server.username, "user");
-  EXPECT_EQ(server.credential, "pass");
-}
-
-TEST_F(RoomTest, RoomWithCustomRtcConfig) {
-  RoomOptions options;
-  options.auto_subscribe = false;
-  options.dynacast = true;
-
-  RtcConfig rtc_config;
-  rtc_config.ice_servers.push_back({"stun:stun.l.google.com:19302", "", ""});
-  rtc_config.ice_servers.push_back({"turn:turn.example.com:3478", "user", "pass"});
-
-  options.rtc_config = rtc_config;
-
-  EXPECT_FALSE(options.auto_subscribe);
-  EXPECT_TRUE(options.dynacast);
-  EXPECT_TRUE(options.rtc_config.has_value());
-  EXPECT_EQ(options.rtc_config->ice_servers.size(), 2);
-}
-
-TEST_F(RoomTest, RemoteParticipantsEmptyBeforeConnect) {
-  Room room;
-  auto participants = room.remoteParticipants();
-  EXPECT_TRUE(participants.empty()) << "Remote participants should be empty before connect";
-}
-
-TEST_F(RoomTest, RemoteParticipantLookupBeforeConnect) {
-  Room room;
-  auto participant = room.remoteParticipant("nonexistent");
-  EXPECT_EQ(participant, nullptr) << "Looking up participant before connect should return nullptr";
-}
-
 // Server-dependent tests - require LIVEKIT_URL and LIVEKIT_TOKEN_A env vars
-class RoomServerTest : public ::testing::Test {
+class RoomTest : public ::testing::Test {
 protected:
   void SetUp() override {
     livekit::initialize(livekit::LogLevel::Info, livekit::LogSink::kConsole);
@@ -112,12 +42,7 @@ class RoomServerTest : public ::testing::Test {
   std::string token_;
 };
 
-TEST_F(RoomServerTest, ConnectToServer) {
-  if (!server_available_) {
-    GTEST_SKIP() << "LIVEKIT_URL and LIVEKIT_TOKEN_A not set, skipping server "
-                    "connection test";
-  }
-
+TEST_F(RoomTest, ConnectToServer) {
   Room room;
   RoomOptions options;
 
@@ -129,19 +54,15 @@ TEST_F(RoomServerTest, ConnectToServer) {
   }
 }
 
-TEST_F(RoomServerTest, ConnectWithInvalidToken) {
-  if (!server_available_) {
-    GTEST_SKIP() << "LIVEKIT_URL not set, skipping invalid token test";
-  }
-
+TEST_F(RoomTest, ConnectWithInvalidToken) {
   Room room;
   RoomOptions options;
 
   bool connected = room.Connect(server_url_, "invalid_token", options);
   EXPECT_FALSE(connected) << "Should fail to connect with invalid token";
 }
 
-TEST_F(RoomServerTest, ConnectWithInvalidUrl) {
+TEST_F(RoomTest, ConnectWithInvalidUrl) {
   Room room;
   RoomOptions options;
 

src/tests/unit/test_audio_source.cpp

@@ -0,0 +1,43 @@
+/*
+ * 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 <gtest/gtest.h>
+#include <livekit/audio_source.h>
+#include <livekit/livekit.h>
+
+namespace livekit::test {
+
+class AudioSourceTest : public ::testing::Test {
+protected:
+  void SetUp() override { livekit::initialize(livekit::LogLevel::Info, livekit::LogSink::kConsole); }
+  void TearDown() override { livekit::shutdown(); }
+};
+
+TEST_F(AudioSourceTest, ConstructAndQueryProperties) {
+  AudioSource source(48000, 1);
+  EXPECT_EQ(source.sample_rate(), 48000);
+  EXPECT_EQ(source.num_channels(), 1);
+  EXPECT_NE(source.ffi_handle_id(), 0u);
+  EXPECT_DOUBLE_EQ(source.queuedDuration(), 0.0);
+}
+
+TEST_F(AudioSourceTest, ClearQueueIsSafeOnFreshSource) {
+  AudioSource source(48000, 2, /*queue_size_ms=*/0);
+  source.clearQueue();
+  EXPECT_DOUBLE_EQ(source.queuedDuration(), 0.0);
+}
+
+} // namespace livekit::test

src/tests/unit/test_data_stream.cpp

@@ -0,0 +1,59 @@
+/*
+ * 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 <gtest/gtest.h>
+#include <livekit/data_stream.h>
+
+#include <type_traits>
+
+namespace livekit::test {
+
+TEST(DataStreamTest, TextStreamReaderConstructAndInfo) {
+  TextStreamInfo info;
+  info.stream_id = "stream-1";
+  info.mime_type = "text/plain";
+  info.topic = "chat";
+  info.timestamp = 42;
+  info.attachments = {"a.txt"};
+
+  TextStreamReader reader(info);
+  EXPECT_EQ(reader.info().stream_id, "stream-1");
+  EXPECT_EQ(reader.info().mime_type, "text/plain");
+  EXPECT_EQ(reader.info().topic, "chat");
+  EXPECT_EQ(reader.info().timestamp, 42);
+  ASSERT_EQ(reader.info().attachments.size(), 1u);
+  EXPECT_EQ(reader.info().attachments.front(), "a.txt");
+}
+
+TEST(DataStreamTest, ByteStreamReaderConstructAndInfo) {
+  ByteStreamInfo info;
+  info.stream_id = "stream-2";
+  info.mime_type = "application/octet-stream";
+  info.topic = "files";
+  info.name = "data.bin";
+
+  ByteStreamReader reader(info);
+  EXPECT_EQ(reader.info().stream_id, "stream-2");
+  EXPECT_EQ(reader.info().name, "data.bin");
+}
+
+TEST(DataStreamTest, WriterTypesAreDerivedFromBase) {
+  static_assert(std::is_base_of_v<BaseStreamWriter, TextStreamWriter>);
+  static_assert(std::is_base_of_v<BaseStreamWriter, ByteStreamWriter>);
+  EXPECT_GT(kStreamChunkSize, 0u);
+}
+
+} // namespace livekit::test

src/tests/unit/test_data_track_error.cpp

@@ -0,0 +1,42 @@
+/*
+ * 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 <gtest/gtest.h>
+#include <livekit/data_track_error.h>
+
+#include "data_track.pb.h"
+
+namespace livekit::test {
+
+TEST(DataTrackErrorTest, PublishErrorFromEmptyProto) {
+  proto::PublishDataTrackError proto_err;
+  PublishDataTrackError err = PublishDataTrackError::fromProto(proto_err);
+  EXPECT_EQ(err.code, PublishDataTrackErrorCode::UNKNOWN);
+}
+
+TEST(DataTrackErrorTest, TryPushErrorFromEmptyProto) {
+  proto::LocalDataTrackTryPushError proto_err;
+  LocalDataTrackTryPushError err = LocalDataTrackTryPushError::fromProto(proto_err);
+  EXPECT_EQ(err.code, LocalDataTrackTryPushErrorCode::UNKNOWN);
+}
+
+TEST(DataTrackErrorTest, SubscribeErrorFromEmptyProto) {
+  proto::SubscribeDataTrackError proto_err;
+  SubscribeDataTrackError err = SubscribeDataTrackError::fromProto(proto_err);
+  EXPECT_EQ(err.code, SubscribeDataTrackErrorCode::UNKNOWN);
+}
+
+} // namespace livekit::test

src/tests/unit/test_data_track_frame.cpp

@@ -0,0 +1,49 @@
+/*
+ * 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 <gtest/gtest.h>
+#include <livekit/data_track_frame.h>
+
+#include <cstdint>
+#include <vector>
+
+#include "data_track.pb.h"
+
+namespace livekit::test {
+
+TEST(DataTrackFrameTest, DefaultConstructed) {
+  DataTrackFrame frame;
+  EXPECT_TRUE(frame.payload.empty());
+  EXPECT_FALSE(frame.user_timestamp.has_value());
+}
+
+TEST(DataTrackFrameTest, PayloadAndTimestampConstructor) {
+  std::vector<std::uint8_t> payload{1, 2, 3};
+  DataTrackFrame frame(std::move(payload), 12345u);
+  ASSERT_EQ(frame.payload.size(), 3u);
+  EXPECT_EQ(frame.payload[0], 1u);
+  ASSERT_TRUE(frame.user_timestamp.has_value());
+  EXPECT_EQ(*frame.user_timestamp, 12345u);
+}
+
+TEST(DataTrackFrameTest, FromOwnedInfoEmptyProto) {
+  proto::DataTrackFrame proto_frame;
+  DataTrackFrame frame = DataTrackFrame::fromOwnedInfo(proto_frame);
+  EXPECT_TRUE(frame.payload.empty());
+  EXPECT_FALSE(frame.user_timestamp.has_value());
+}
+
+} // namespace livekit::test