From 0e977af7406b5e26234b4b069bc019547f0a585d Mon Sep 17 00:00:00 2001 From: prime Date: Thu, 15 Oct 2026 16:20:30 +0200 Subject: [PATCH] feat: Room.restartIce() to move media off a degraded candidate pair Once UDP is blocked, libwebrtc falls back to a TURN relay over TCP/TLS and stays there after UDP comes back, until something restarts ICE. On a link measured end to end, that path sent 3x less video, froze 5x more often and added about 150 ms of audio latency. An app can see the selected pair in getStats(), but had no public way to restart ICE: Engine, handleReconnect and ClientDisconnectReason are internal. Room.restartIce() reuses the regular resume path with RR_SWITCH_CANDIDATE, the protocol's reason for this case: an iceRestart offer for the publisher, while the server restarts the subscriber. The mock peer connection now implements restartIce() as a no-op, which the resume path calls on native platforms. Co-Authored-By: Claude Opus 5.5 --- .changes/room-restart-ice | 1 + lib/src/core/room.dart | 11 +++++ test/core/restart_ice_test.dart | 74 ++++++++++++++++++++++++++++++ test/mock/peerconnection_mock.dart | 3 +- 4 files changed, 87 insertions(+), 2 deletions(-) create mode 100644 .changes/room-restart-ice create mode 100644 test/core/restart_ice_test.dart diff --git a/.changes/room-restart-ice b/.changes/room-restart-ice new file mode 100644 index 000000000..efd964375 --- /dev/null +++ b/.changes/room-restart-ice @@ -0,0 +1 @@ +minor type="added" "`Room.restartIce()` resumes the session on purpose to restart ICE on both peer connections, so media stuck on a TURN relay over TCP/TLS can move back to UDP" diff --git a/lib/src/core/room.dart b/lib/src/core/room.dart index 4ef28bbf0..b801c762b 100644 --- a/lib/src/core/room.dart +++ b/lib/src/core/room.dart @@ -50,6 +50,7 @@ import '../track/local/video.dart'; import '../track/track.dart'; import '../track/web/_audio_api.dart' if (dart.library.js_interop) '../track/web/_audio_html.dart' as audio; import '../types/data_stream.dart'; +import '../types/internal.dart'; import '../types/other.dart'; import '../types/rpc.dart'; import '../types/transcription_segment.dart'; @@ -760,6 +761,16 @@ class Room extends DisposableChangeNotifier with EventsEmittable { } }); + /// Resumes the session on purpose, restarting ICE on both peer connections. + /// + /// Once UDP is blocked, media falls back to a TURN relay over TCP/TLS and + /// stays there after UDP comes back. An app that sees from the stats that a + /// better path is available again can call this to let ICE find it. + Future restartIce() => engine.handleReconnect( + ClientDisconnectReason.reconnect, + reconnectReason: lk_models.ReconnectReason.RR_SWITCH_CANDIDATE, + ); + /// Disconnects from the room, notifying server of disconnection. Future disconnect() async { final bool isPendingReconnect = engine.isPendingReconnect; diff --git a/test/core/restart_ice_test.dart b/test/core/restart_ice_test.dart new file mode 100644 index 000000000..e05807b15 --- /dev/null +++ b/test/core/restart_ice_test.dart @@ -0,0 +1,74 @@ +// Copyright 2026 LiveKit, Inc. +// +// 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. + +@Timeout(Duration(seconds: 10)) +library; + +import 'package:flutter_test/flutter_test.dart'; +import 'package:flutter_webrtc/flutter_webrtc.dart' as rtc; + +import 'package:livekit_client/livekit_client.dart'; +import 'package:livekit_client/src/proto/livekit_models.pb.dart' as lk_models; +import 'package:livekit_client/src/proto/livekit_rtc.pb.dart' as lk_rtc; +import '../mock/e2e_container.dart'; +import '../mock/peerconnection_mock.dart'; +import '../mock/websocket_mock.dart'; + +void main() { + TestWidgetsFlutterBinding.ensureInitialized(); + + late E2EContainer container; + late MockWebSocketConnector ws; + + setUp(() async { + resetMockDataChannels(); + container = E2EContainer(); + ws = container.wsConnector; + await container.connectRoom(); + }); + + tearDown(() async { + await container.dispose(); + }); + + Future until(bool Function() condition) async { + for (var i = 0; i < 200 && !condition(); i++) { + await Future.delayed(const Duration(milliseconds: 10)); + } + expect(condition(), isTrue); + } + + test('restartIce() resumes to switch candidates, restarting publisher ICE', () async { + final publisher = container.engine.publisher!; + await container.engine.negotiate(); + await until(() => publisher.pc.signalingState == rtc.RTCSignalingState.RTCSignalingStateHaveLocalOffer); + ws.onData( + lk_rtc.SignalResponse( + answer: lk_rtc.SessionDescription(type: 'answer', sdp: 'remote_answer'), + ).writeToBuffer(), + ); + await until(() => publisher.pc.connectionState == rtc.RTCPeerConnectionState.RTCPeerConnectionStateConnected); + + final previousHandlers = ws.handlers; + await container.room.restartIce(); + await until(() => !identical(ws.handlers, previousHandlers)); + + expect(ws.uri!.queryParameters['reconnect'], '1'); + expect(ws.uri!.queryParameters['reconnect_reason'], '${lk_models.ReconnectReason.RR_SWITCH_CANDIDATE.value}'); + + ws.onData(lk_rtc.SignalResponse(reconnect: lk_rtc.ReconnectResponse()).writeToBuffer()); + await container.room.events.waitFor(duration: const Duration(seconds: 5)); + expect(publisher.restartingIce, isTrue); + }); +} diff --git a/test/mock/peerconnection_mock.dart b/test/mock/peerconnection_mock.dart index 1dc3c8755..435359359 100644 --- a/test/mock/peerconnection_mock.dart +++ b/test/mock/peerconnection_mock.dart @@ -300,6 +300,5 @@ a=rtpmap:32 MPV/90000 ]) async => MockPeerConnection(); @override - // TODO: implement restartIce - Future restartIce() => throw UnimplementedError(); + Future restartIce() async {} }