Wrap SimulateScenario to test server-initiated reconnect/leave paths

Adds Room::simulateScenario(SimulateScenario) over a new
FfiClient::simulateScenarioAsync, a public SimulateScenario enum, and the
proto mapping — mirroring the disconnect() async pattern. This surfaces the
Rust core's chaos/reconnect hook so tests can drive the previously
zero-coverage server-initiated paths in-band, without server-admin calls.

Tests:
- unit: simulateScenario on a disconnected room throws (no server needed)
- integration: SignalReconnect and FullReconnect drive onReconnecting/
  onReconnected; ServerLeave drives a server-initiated onDisconnected

Updates docs/connection-lifecycle.md coverage matrix accordingly.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: alan-george-lk

docs/connection-lifecycle.md

@@ -98,10 +98,12 @@ live server (see `docs/testing.md`).
 | D4 | `livekit::shutdown()` while a Room is still connected | — | ❌ none |
 | D5 | SIGINT/SIGTERM during a session | — | ❌ none (by design: app responsibility, but undocumented) |
 | D6 | Process exit without shutdown (warning path) | — | ❌ none |
-| S1 | Server-initiated `kDisconnected` (kick, room deletion, duplicate identity) | — | ❌ none — no test kicks a participant or deletes a room |
+| S1 | Server-initiated `kDisconnected` via `ServerLeave` | `integration/test_room_reconnect.cpp` `ServerLeaveDisconnects` | ✅ (SimulateScenario) |
+| S1 | Server-initiated `kDisconnected` (kick, room deletion, duplicate identity) | — | ❌ none — needs server-admin API or fake injector |
 | S2 | `kEos` teardown | — | ❌ none |
 | S1×D1 | Race: server disconnect vs. client disconnect | — | ❌ none |
-| S3 | Reconnecting/Reconnected callbacks | — | ❌ none |
+| S3 | Reconnecting/Reconnected callbacks | `integration/test_room_reconnect.cpp` `SignalReconnectResumesSession`, `FullReconnectReestablishesSession` | ✅ (SimulateScenario) |
+| — | `simulateScenario` on a disconnected room throws | `unit/test_room.cpp` `SimulateScenarioOnDisconnectedRoomThrows` | ✅ |
 | S4 | ConnectionStateChanged callback | — | ❌ none |
 | S5 | FFI panic → SIGTERM | `unit/test_ffi_client.cpp` (SIGTERM handler + flag) | ✅ |
 | S6 | Remote participant disconnects | — | ❌ none (only reachable with a second participant) |
@@ -173,10 +175,13 @@ request/async-callback shape the C++ `FfiClient` already uses for connect/discon
 | 7 | `FULL_RECONNECT` | Server sends `Leave{Reconnect}` → new `RtcSession`, tracks republished | S3, full-reconnect + republish |
 | 8 | `DISCONNECT_SIGNAL_ON_RESUME` | Drops signalling mid-resume → forces resume→full escalation | S3, escalation path |
 
-**Status in this SDK: not wrapped.** There is no reference to `simulate` anywhere
-in `src/`, and `FfiClient` has no `simulateScenarioAsync`. The Rust core supports
-it (and the rust-sdks own `reconnection_test.rs`, `data_channel_test.rs`, etc. use
-it), but the C++ layer has never surfaced it.
+**Status in this SDK: wrapped.** Exposed as `Room::simulateScenario(SimulateScenario)`
+(`include/livekit/room.h`, `src/room.cpp`) over `FfiClient::simulateScenarioAsync`
+(`src/ffi_client.cpp`), with the C++ `SimulateScenario` enum in
+`include/livekit/room_event_types.h` and proto mapping in
+`src/room_proto_converter.cpp`. It throws if the room is not connected and blocks
+on the FFI callback (so it must not be called from inside a delegate callback,
+same as `disconnect()`).
 
 **Important:** `SimulateScenario` is an *in-band* hook forwarded over the live
 signalling connection — it still requires a real server. It does **not** replace a
@@ -195,15 +200,12 @@ Two complementary mechanisms, at different layers:
    way to cover S2/S1×D1 deterministically and offline. `SimulateScenario` does
    *not* help here (it needs a server).
 
-2. **Wrap `SimulateScenario` (integration, live server)** — add a thin
-   `FfiClient::simulateScenarioAsync(room_handle, kind)` plus a `Room` hook (or a
-   test-only accessor), mirroring `disconnectAsync` exactly; the proto is already
-   generated from the submodule. This is the clean way to drive the currently
-   **zero-coverage S3 reconnect paths** (`SIGNAL_RECONNECT`, `NODE_FAILURE`,
-   `FULL_RECONNECT`, `DISCONNECT_SIGNAL_ON_RESUME`) and a server-initiated
-   disconnect (`SERVER_LEAVE` → S1/S2) end-to-end, without server-admin calls.
-   It is the primary unlock for `onReconnecting`/`onReconnected` coverage, which no
-   C++ test currently touches.
+2. **`SimulateScenario` (integration, live server) — done.** `Room::simulateScenario`
+   now drives these paths; `integration/test_room_reconnect.cpp` covers
+   `SignalReconnect` and `FullReconnect` (S3 reconnecting→reconnected) and
+   `ServerLeave` (S1 server-initiated disconnect). Remaining scenarios worth adding
+   as they prove useful: `NodeFailure`, `Migration`, and `DisconnectSignalOnResume`
+   (resume→full escalation).
 
 Reason-specific disconnects that `SimulateScenario` does **not** cover
 (`ParticipantRemoved`, `RoomDeleted`, `DuplicateIdentity`) still need either the

include/livekit/room.h

@@ -181,6 +181,27 @@ class LIVEKIT_API Room {
   ///          room was already disconnected (no-op) or the graceful disconnect fails.
   bool disconnect(DisconnectReason reason = DisconnectReason::ClientInitiated);
 
+  /// Inject a reconnection / chaos scenario for testing.
+  ///
+  /// Drives the Rust core's `SimulateScenario` in-band over the live signalling
+  /// connection. This exists to exercise the server-initiated reconnect and
+  /// leave paths (which no other client API reaches) end-to-end without
+  /// server-admin calls. It is intended for tests and chaos tooling, not
+  /// production traffic.
+  ///
+  /// Depending on the scenario, expect subsequent delegate callbacks such as
+  /// @ref RoomDelegate::onReconnecting / @ref RoomDelegate::onReconnected (the
+  /// reconnect scenarios) or @ref RoomDelegate::onDisconnected (ServerLeave).
+  ///
+  /// @warning Safe to call from any thread, but **must not** be called from
+  /// inside a `RoomDelegate` callback — doing so will deadlock the event
+  /// listener, since this blocks on the FFI callback delivered on that thread.
+  ///
+  /// @param scenario The scenario to inject.
+  /// @returns true if the FFI accepted the request; false if it failed.
+  /// @throws std::runtime_error if the room is not currently connected.
+  bool simulateScenario(SimulateScenario scenario);
+
   // Accessors
 
   /// Retrieve static metadata about the room.

include/livekit/room_event_types.h

@@ -96,6 +96,36 @@ enum class DisconnectReason {
   MediaFailure
 };
 
+/// Reconnection / chaos scenarios that can be injected at runtime for testing.
+///
+/// These map 1:1 to the Rust core's `SimulateScenario` (proto
+/// `SimulateScenarioKind`) and are driven in-band over the live signalling
+/// connection via @ref Room::simulateScenario. They exist to exercise the
+/// server-initiated reconnect and leave paths (which no client API otherwise
+/// reaches) without needing server-admin calls. Intended for tests and chaos
+/// tooling, not production traffic.
+enum class SimulateScenario {
+  /// Close the signal channel locally; the engine attempts a resume.
+  SignalReconnect = 0,
+  /// Simulate local speaker activity (surfaces via onActiveSpeakersChanged).
+  Speaker,
+  /// Simulate a media node failure, triggering reconnection.
+  NodeFailure,
+  /// Ask the server to send a Leave, producing a server-initiated disconnect.
+  ServerLeave,
+  /// Simulate a server migration.
+  Migration,
+  /// Force ICE to use TCP, triggering a transport reconnect.
+  ForceTcp,
+  /// Force ICE to use TLS, triggering a transport reconnect.
+  ForceTls,
+  /// Ask the server to send Leave{Reconnect}, forcing a full reconnect
+  /// (new session; the SDK republishes existing local tracks).
+  FullReconnect,
+  /// Drop signalling mid-resume, forcing the resume->full-reconnect escalation.
+  DisconnectSignalOnResume
+};
+
 /// Application-level user data carried in a data packet.
 struct UserPacketData {
   /// Raw payload bytes.

src/ffi_client.cpp

@@ -71,6 +71,8 @@ std::optional<FfiClient::AsyncId> ExtractAsyncId(const proto::FfiEvent& event) {
       return event.connect().async_id();
     case E::kDisconnect:
       return event.disconnect().async_id();
+    case E::kSimulateScenario:
+      return event.simulate_scenario().async_id();
     case E::kDispose:
       return event.dispose().async_id();
     case E::kPublishTrack:
@@ -540,6 +542,42 @@ std::future<void> FfiClient::disconnectAsync(uintptr_t room_handle, DisconnectRe
   return fut;
 }
 
+std::future<void> FfiClient::simulateScenarioAsync(uintptr_t room_handle, SimulateScenario scenario) {
+  const AsyncId async_id = generateAsyncId();
+
+  auto fut = registerAsync<void>(
+      async_id,
+      [async_id](const proto::FfiEvent& event) {
+        return event.has_simulate_scenario() && event.simulate_scenario().async_id() == async_id;
+      },
+      [](const proto::FfiEvent& event, std::promise<void>& pr) {
+        const auto& cb = event.simulate_scenario();
+        if (cb.has_error() && !cb.error().empty()) {
+          pr.set_exception(std::make_exception_ptr(std::runtime_error(cb.error())));
+          return;
+        }
+        pr.set_value();
+      });
+
+  proto::FfiRequest req;
+  auto* simulate = req.mutable_simulate_scenario();
+  simulate->set_room_handle(room_handle);
+  simulate->set_request_async_id(async_id);
+  simulate->set_scenario(toProto(scenario));
+
+  try {
+    const proto::FfiResponse resp = sendRequest(req);
+    if (!resp.has_simulate_scenario()) {
+      logAndThrow("FfiResponse missing simulate_scenario");
+    }
+  } catch (...) {
+    cancelPendingByAsyncId(async_id);
+    throw;
+  }
+
+  return fut;
+}
+
 // Track APIs Implementation
 std::future<std::vector<RtcStats>> FfiClient::getTrackStatsAsync(uintptr_t track_handle) {
   // Generate client-side async_id first

src/ffi_client.h

@@ -99,6 +99,9 @@ class LIVEKIT_INTERNAL_API FfiClient {
 
   std::future<void> disconnectAsync(uintptr_t room_handle, DisconnectReason reason);
 
+  // Inject a reconnection / chaos scenario for testing (SimulateScenario).
+  std::future<void> simulateScenarioAsync(uintptr_t room_handle, SimulateScenario scenario);
+
   // Track APIs
   std::future<std::vector<RtcStats>> getTrackStatsAsync(uintptr_t track_handle);
 

src/room.cpp

@@ -292,6 +292,30 @@ bool Room::disconnect(DisconnectReason reason) {
   return ffi_ok;
 }
 
+bool Room::simulateScenario(SimulateScenario scenario) {
+  TRACE_EVENT0("livekit", "Room::simulateScenario");
+
+  std::shared_ptr<FfiHandle> handle;
+  {
+    const std::scoped_lock<std::mutex> g(lock_);
+    if (connection_state_ != ConnectionState::Connected) {
+      throw std::runtime_error("Room::simulateScenario called on a room that is not connected");
+    }
+    handle = room_handle_;
+  }
+  if (!handle) {
+    throw std::runtime_error("Room::simulateScenario: missing room handle");
+  }
+
+  try {
+    FfiClient::instance().simulateScenarioAsync(handle->get(), scenario).get();
+    return true;
+  } catch (const std::exception& e) {
+    LK_LOG_ERROR("Room::simulateScenario failed: {}", e.what());
+    return false;
+  }
+}
+
 RoomInfoData Room::roomInfo() const {
   const std::scoped_lock<std::mutex> g(lock_);
   return room_info_;

src/room_proto_converter.cpp

@@ -191,6 +191,31 @@ proto::DisconnectReason toProto(DisconnectReason in) {
   }
 }
 
+proto::SimulateScenarioKind toProto(SimulateScenario in) {
+  switch (in) {
+    case SimulateScenario::SignalReconnect:
+      return proto::SIMULATE_SIGNAL_RECONNECT;
+    case SimulateScenario::Speaker:
+      return proto::SIMULATE_SPEAKER;
+    case SimulateScenario::NodeFailure:
+      return proto::SIMULATE_NODE_FAILURE;
+    case SimulateScenario::ServerLeave:
+      return proto::SIMULATE_SERVER_LEAVE;
+    case SimulateScenario::Migration:
+      return proto::SIMULATE_MIGRATION;
+    case SimulateScenario::ForceTcp:
+      return proto::SIMULATE_FORCE_TCP;
+    case SimulateScenario::ForceTls:
+      return proto::SIMULATE_FORCE_TLS;
+    case SimulateScenario::FullReconnect:
+      return proto::SIMULATE_FULL_RECONNECT;
+    case SimulateScenario::DisconnectSignalOnResume:
+      return proto::SIMULATE_DISCONNECT_SIGNAL_ON_RESUME;
+    default:
+      return proto::SIMULATE_SIGNAL_RECONNECT;
+  }
+}
+
 // --------- basic helper conversions ---------
 
 UserPacketData fromProto(const proto::UserPacket& in) {

src/room_proto_converter.h

@@ -39,6 +39,7 @@ LIVEKIT_INTERNAL_API ConnectionState toConnectionState(proto::ConnectionState in
 LIVEKIT_INTERNAL_API DataPacketKind toDataPacketKind(proto::DataPacketKind in);
 LIVEKIT_INTERNAL_API DisconnectReason toDisconnectReason(proto::DisconnectReason in);
 LIVEKIT_INTERNAL_API proto::DisconnectReason toProto(DisconnectReason in);
+LIVEKIT_INTERNAL_API proto::SimulateScenarioKind toProto(SimulateScenario in);
 
 LIVEKIT_INTERNAL_API UserPacketData fromProto(const proto::UserPacket& in);
 LIVEKIT_INTERNAL_API SipDtmfData fromProto(const proto::SipDTMF& in);