Skip to content

Commit 298cc62

Browse files
hiroshihorieclaude
andauthored
fix: keep the pre-connect audio buffer through a region failover on connect (#1215)
## Problem When the first connect attempt fails, the engine reports a disconnect before `Room.connect` retries another Cloud region. The Room handled that disconnect like any other and reset the pre-connect audio buffer. The retry then connected with a buffer that was no longer recording, so the join response found no microphone track to publish. The participant ended up in the room, joined unmuted, with no microphone until they toggled it. Since 2.13.0 a 403 rejection also fails over instead of failing the connect, so a first attempt that used to fail visibly now connects silently without the microphone. ## Fix - `Room.connect` records that a connect attempt is running. - The engine disconnect handler passes that state to `_cleanUp`, which skips the pre-connect buffer reset when the disconnect belongs to a connect attempt that may still be retried. - A disconnect the app asked for always resets the buffer, also during a connect. Otherwise a `disconnect()` called while the connect is in flight would leave the buffer recording, and the microphone would be published if that connect completed. - When a failed attempt was handed to the failover path and no attempt connects (no region left, the region fetch fails, or the retry fails too), `connect()` stops the buffer with the error before it throws, the way `withPreConnectAudio` ends a failed operation, and then resets it. Stopping with the error is what also stops the native recorder. - A disconnect outside of a connect attempt still resets the buffer, as before. ## Tests `test/core/preconnect_failover_test.dart` covers each way `connect()` can end. Every test fails when the part of the fix it guards is removed. | Case | Buffer afterwards | |---|---| | first socket connect fails, validate answers 403, the retry connects | still recording (fails on `main`) | | the socket is rejected while validate succeeds, the retry connects | still recording (fails on `main`) | | connect fails with no failover (not a Cloud url) | reset | | the failover has no region left | stopped with the connect error, then reset | | the failover attempt fails too | stopped with the connect error, then reset | | `disconnect()` is called while the socket handshake is in flight | reset | | a server initiated leave while connected | reset | Test-only additions: `Room.regionUrlProviderForTesting`, `PreConnectAudioBuffer.markRecordingForTesting`, `sdkHttpClientFactoryForTesting`, and two switches on the websocket mock: `connectErrorOnce`, so a first attempt fails and the retry gets through, and `connectGate`, so a handshake can be held in flight. `flutter analyze`, format and import order are clean, and the full unit suite is green (595 tests). ## Verified on devices The e2e-flutter scenario "Local mic transmits, published through pre-connect audio". **iPhone 16 Pro (iOS 27.2) against a region-pinned LiveKit Cloud project.** There the first connect attempt is rejected with a 403 and fails over to another region on every run. | SDK | Result | |---|---| | `main` (a40ca98) | failed 5 of 5: the microphone track is never published, because the buffer is reset during the failover | | `main` before #1280 (4dae650) | failed, so this is not a #1280 regression | | this PR at ee3fbc8 | passed 6 of 6: failover happens, the pre-connect track is published, and microphone audio reaches the subscriber | The iPhone runs predate the last two commits (f9c394b, ec7b96d), which only change what happens when a connect is cancelled or its failover gives up. **macOS against a local server, at ec7b96d**, with the failover forced locally (livekit/e2e-flutter#33): - the microphone set passes 10 of 10, including pre-connect audio with and without a failover - without the fix, the failover variant fails: the retry joins with no microphone ## Changes since the first version - Rebased onto `main` (a40ca98). The only conflict was in `test/mock/websocket_mock.dart`: `main` added `sentData` next to this PR's `connectErrorOnce`, and both are kept. - Added the changeset `.changes/preconnect-audio-survives-failover`. - e399ee3: `markRecordingForTesting` had been inserted between `startRecording` and its doc comment; moved it so the documentation stays on `startRecording`. - f9c394b: the two reset rules above for a cancelled connect and a failover that gives up, with the five new test cases. - ec7b96d: when a failover gives up, stop the buffer with the error instead of a plain reset, which left the native recorder running (found by the automated review of f9c394b). 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
1 parent a40ca98 commit 298cc62

6 files changed

Lines changed: 277 additions & 21 deletions

File tree

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
patch type="fixed" "Keep the pre-connect audio buffer recording through a region failover on connect, so the microphone is still published when the first attempt is rejected (for example by a region-pinned LiveKit Cloud project)"

‎lib/src/core/room.dart‎

Lines changed: 55 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -133,6 +133,19 @@ class Room extends DisposableChangeNotifier with EventsEmittable<RoomEvent> {
133133
late EventsListener<SignalEvent> _signalListener;
134134

135135
RegionUrlProvider? _regionUrlProvider;
136+
137+
/// True while [connect] is running. A failed attempt tears the engine down
138+
/// and reports a disconnect before [connect] retries another region, and
139+
/// that cleanup must not throw away state the retry still needs.
140+
bool _connectInProgress = false;
141+
142+
/// Lets tests install a provider with known regions, so a failover can be
143+
/// exercised without reaching a real LiveKit Cloud endpoint.
144+
@visibleForTesting
145+
set regionUrlProviderForTesting(RegionUrlProvider? provider) {
146+
_regionUrlProvider = provider;
147+
}
148+
136149
String? _regionUrl;
137150

138151
// Agents
@@ -368,6 +381,7 @@ class Room extends DisposableChangeNotifier with EventsEmittable<RoomEvent> {
368381
await NativeAudioManagement.start();
369382

370383
var didConnect = false;
384+
_connectInProgress = true;
371385
try {
372386
await engine.connect(
373387
_regionUrl ?? url,
@@ -381,32 +395,43 @@ class Room extends DisposableChangeNotifier with EventsEmittable<RoomEvent> {
381395
} catch (e) {
382396
logger.warning('could not connect to $url $e');
383397
if (_regionUrlProvider != null && canFailOverToAnotherRegion(e)) {
384-
String? nextUrl;
385398
try {
386-
nextUrl = await _regionUrlProvider!.getNextBestRegionUrl();
387-
} catch (error) {
388-
if (error is ConnectException && (error.statusCode == 401)) {
399+
String? nextUrl;
400+
try {
401+
nextUrl = await _regionUrlProvider!.getNextBestRegionUrl();
402+
} catch (error) {
403+
if (error is ConnectException && (error.statusCode == 401)) {
404+
rethrow;
405+
}
406+
}
407+
if (nextUrl != null) {
408+
logger.fine('Initial connection failed with ConnectionError: $e. Retrying with another region: ${nextUrl}');
409+
await engine.connect(
410+
nextUrl,
411+
token,
412+
connectOptions: connectOptions,
413+
roomOptions: effectiveRoomOptions,
414+
fastConnectOptions: fastConnectOptions,
415+
regionUrlProvider: _regionUrlProvider,
416+
);
417+
didConnect = true;
418+
} else {
389419
rethrow;
390420
}
391-
}
392-
if (nextUrl != null) {
393-
logger.fine('Initial connection failed with ConnectionError: $e. Retrying with another region: ${nextUrl}');
394-
await engine.connect(
395-
nextUrl,
396-
token,
397-
connectOptions: connectOptions,
398-
roomOptions: effectiveRoomOptions,
399-
fastConnectOptions: fastConnectOptions,
400-
regionUrlProvider: _regionUrlProvider,
401-
);
402-
didConnect = true;
403-
} else {
421+
} catch (error) {
422+
// The cleanup for the failed attempt left the pre-connect audio
423+
// buffer recording for a retry, and no retry connected. Stop it
424+
// with the error, the way withPreConnectAudio ends a failed
425+
// operation, so the native recorder is stopped as well.
426+
await preConnectAudioBuffer.stopRecording(withError: error);
427+
await preConnectAudioBuffer.reset();
404428
rethrow;
405429
}
406430
} else {
407431
rethrow;
408432
}
409433
} finally {
434+
_connectInProgress = false;
410435
if (!didConnect) {
411436
await NativeAudioManagement.stop();
412437
}
@@ -676,7 +701,15 @@ class Room extends DisposableChangeNotifier with EventsEmittable<RoomEvent> {
676701
// pending one when it starts.
677702
if ((!engine.fullReconnectOnNext && !engine.isFullReconnectInProgress) ||
678703
event.reason == DisconnectReason.clientInitiated) {
679-
await _cleanUp(disposeLocalParticipant: false);
704+
// A failed first attempt lands here before connect() retries another
705+
// region. The pre-connect audio buffer has to survive that, or the
706+
// retry connects without ever publishing the microphone. A disconnect
707+
// the app asked for is not a retry: it resets the buffer as always, so
708+
// nothing is published if that connect still completes.
709+
await _cleanUp(
710+
disposeLocalParticipant: false,
711+
preservePreConnectAudio: _connectInProgress && event.reason != DisconnectReason.clientInitiated,
712+
);
680713
events.emit(RoomDisconnectedEvent(reason: event.reason));
681714
notifyListeners();
682715
}
@@ -1133,7 +1166,7 @@ class Room extends DisposableChangeNotifier with EventsEmittable<RoomEvent> {
11331166

11341167
extension RoomPrivateMethods on Room {
11351168
// resets internal state to a re-usable state
1136-
Future<void> _cleanUp({bool disposeLocalParticipant = true}) async {
1169+
Future<void> _cleanUp({bool disposeLocalParticipant = true, bool preservePreConnectAudio = false}) async {
11371170
logger.fine('[${objectId}] cleanUp()');
11381171

11391172
// Fail any open data streams so their handlers return rather than awaiting a reader that will
@@ -1161,7 +1194,9 @@ extension RoomPrivateMethods on Room {
11611194

11621195
_activeSpeakers.clear();
11631196

1164-
await preConnectAudioBuffer.reset();
1197+
if (!preservePreConnectAudio) {
1198+
await preConnectAudioBuffer.reset();
1199+
}
11651200

11661201
// clean up engine
11671202
await engine.cleanUp();

‎lib/src/preconnect/pre_connect_audio_buffer.dart‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414

1515
import 'dart:async';
1616

17+
import 'package:meta/meta.dart';
1718
import 'package:uuid/uuid.dart';
1819

1920
import '../audio/audio_frame_capture.dart';
@@ -97,6 +98,14 @@ class PreConnectAudioBuffer {
9798
/// future completes with an error.
9899
Future<void> get agentReadyFuture => _agentReadyManager.future;
99100

101+
/// Puts the buffer into its recording state without touching the
102+
/// microphone, so tests can check what the Room does with a live buffer
103+
/// where no audio device exists.
104+
@visibleForTesting
105+
void markRecordingForTesting() {
106+
_isRecording = true;
107+
}
108+
100109
/// Starts capturing audio into an in-memory buffer.
101110
///
102111
/// [timeout] controls how long to wait for an agent to become active. When the

‎lib/src/support/http_client.dart‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,18 @@
1313
// limitations under the License.
1414

1515
import 'package:http/http.dart' as http;
16+
import 'package:meta/meta.dart';
1617

1718
import '../options.dart';
1819
import 'http_client/io.dart' if (dart.library.js_interop) 'http_client/web.dart' as impl;
1920

20-
http.Client createSdkHttpClient(NetworkOptions networkOptions) => impl.createSdkHttpClient(networkOptions);
21+
/// Replaces the HTTP client the SDK builds, so tests can answer the requests
22+
/// the SDK makes on its own, such as the validate call after a failed connect.
23+
@visibleForTesting
24+
http.Client Function(NetworkOptions networkOptions)? sdkHttpClientFactoryForTesting;
25+
26+
http.Client createSdkHttpClient(NetworkOptions networkOptions) =>
27+
sdkHttpClientFactoryForTesting?.call(networkOptions) ?? impl.createSdkHttpClient(networkOptions);
2128

2229
Future<http.Response> sdkHttpGet(
2330
Uri uri, {
Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
// Copyright 2026 LiveKit, Inc.
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
@Timeout(Duration(seconds: 10))
16+
library;
17+
18+
import 'dart:async';
19+
20+
import 'package:flutter_test/flutter_test.dart';
21+
import 'package:http/http.dart' as http;
22+
import 'package:http/testing.dart';
23+
24+
import 'package:livekit_client/livekit_client.dart';
25+
import 'package:livekit_client/src/proto/livekit_models.pb.dart' as lk_models;
26+
import 'package:livekit_client/src/proto/livekit_rtc.pb.dart' as lk_rtc;
27+
import 'package:livekit_client/src/support/http_client.dart';
28+
import 'package:livekit_client/src/support/region_url_provider.dart';
29+
import 'package:livekit_client/src/support/websocket.dart';
30+
import '../mock/e2e_container.dart';
31+
32+
const cloudUri = 'wss://test.livekit.cloud';
33+
const token = 'token';
34+
35+
/// A provider that already knows its regions, so a failover never has to
36+
/// fetch them. With no [regions] there is nowhere left to fail over to.
37+
RegionUrlProvider providerWith(List<String> regions) =>
38+
RegionUrlProvider(url: cloudUri, token: token)..setServerReportedRegions(
39+
lk_rtc.RegionSettings()
40+
..regions.addAll([
41+
for (final region in regions)
42+
lk_rtc.RegionInfo()
43+
..region = region
44+
..url = 'wss://$region.livekit.cloud',
45+
]),
46+
);
47+
48+
void main() {
49+
TestWidgetsFlutterBinding.ensureInitialized();
50+
51+
late E2EContainer container;
52+
53+
// What the validate request answers after a failed socket connect. A 403 is
54+
// one of the answers that makes connect() fail over to another region.
55+
late int validateStatus;
56+
57+
setUp(() {
58+
container = E2EContainer();
59+
validateStatus = 403;
60+
sdkHttpClientFactoryForTesting = (_) => MockClient(
61+
(request) async => validateStatus == 200
62+
? http.Response('success', 200)
63+
: http.Response('project not allowed in this region.', validateStatus),
64+
);
65+
});
66+
67+
tearDown(() async {
68+
sdkHttpClientFactoryForTesting = null;
69+
await container.dispose();
70+
});
71+
72+
test('pre-connect audio buffer survives a region failover on the first attempt', () async {
73+
final room = container.room;
74+
75+
// Known regions, so a failed first attempt retries another region instead
76+
// of failing the connect.
77+
room.regionUrlProviderForTesting = providerWith(['other']);
78+
room.preConnectAudioBuffer.markRecordingForTesting();
79+
80+
// The first socket connect fails, the retry gets through.
81+
container.wsConnector.connectError = WebSocketException('first region down');
82+
container.wsConnector.connectErrorOnce = true;
83+
final connecting = room.connect(cloudUri, token);
84+
await container.answerJoin();
85+
await connecting;
86+
87+
expect(room.connectionState, ConnectionState.connected);
88+
expect(container.wsConnector.uri.toString(), startsWith('wss://other.livekit.cloud'));
89+
// The buffered microphone track is published from the join response, so
90+
// the cleanup that runs for the failed attempt must leave the buffer alone.
91+
expect(room.preConnectAudioBuffer.isRecording, isTrue);
92+
});
93+
94+
test('pre-connect audio buffer survives a failover when only the socket is rejected', () async {
95+
final room = container.room;
96+
room.regionUrlProviderForTesting = providerWith(['other']);
97+
room.preConnectAudioBuffer.markRecordingForTesting();
98+
99+
// The socket is refused while the validate request succeeds, so connect()
100+
// fails over on the socket error itself.
101+
validateStatus = 200;
102+
container.wsConnector.connectError = WebSocketException('rejected');
103+
container.wsConnector.connectErrorOnce = true;
104+
final connecting = room.connect(cloudUri, token);
105+
await container.answerJoin();
106+
await connecting;
107+
108+
expect(room.connectionState, ConnectionState.connected);
109+
expect(container.wsConnector.uri.toString(), startsWith('wss://other.livekit.cloud'));
110+
expect(room.preConnectAudioBuffer.isRecording, isTrue);
111+
});
112+
113+
test('pre-connect audio buffer is reset when connect fails with no failover', () async {
114+
final room = container.room;
115+
room.preConnectAudioBuffer.markRecordingForTesting();
116+
117+
// Not a LiveKit Cloud url, so there is no other region to try.
118+
validateStatus = 401;
119+
container.wsConnector.connectError = WebSocketException('down');
120+
await expectLater(room.connect('wss://self.hosted.example', token), throwsA(isA<ConnectException>()));
121+
await Future<void>.delayed(const Duration(milliseconds: 200));
122+
123+
expect(room.preConnectAudioBuffer.isRecording, isFalse);
124+
});
125+
126+
test('pre-connect audio buffer is reset when the failover has no region left', () async {
127+
final room = container.room;
128+
room.regionUrlProviderForTesting = providerWith([]);
129+
room.preConnectAudioBuffer.markRecordingForTesting();
130+
// Stopped with the connect error, which is what also stops the native
131+
// recorder, rather than with a plain reset.
132+
final agentReady = expectLater(room.preConnectAudioBuffer.agentReadyFuture, throwsA(isA<ConnectException>()));
133+
134+
container.wsConnector.connectError = WebSocketException('down');
135+
await expectLater(room.connect(cloudUri, token), throwsA(isA<ConnectException>()));
136+
await agentReady;
137+
138+
expect(room.preConnectAudioBuffer.isRecording, isFalse);
139+
});
140+
141+
test('pre-connect audio buffer is reset when the failover attempt fails too', () async {
142+
final room = container.room;
143+
room.regionUrlProviderForTesting = providerWith(['other']);
144+
room.preConnectAudioBuffer.markRecordingForTesting();
145+
final agentReady = expectLater(room.preConnectAudioBuffer.agentReadyFuture, throwsA(isA<ConnectException>()));
146+
147+
container.wsConnector.connectError = WebSocketException('down');
148+
await expectLater(room.connect(cloudUri, token), throwsA(isA<ConnectException>()));
149+
await agentReady;
150+
151+
expect(room.preConnectAudioBuffer.isRecording, isFalse);
152+
});
153+
154+
test('pre-connect audio buffer is reset when disconnect() is called during connect', () async {
155+
final room = container.room;
156+
room.preConnectAudioBuffer.markRecordingForTesting();
157+
158+
// The socket handshake is still in flight when the app gives up. A buffer
159+
// left recording here would publish the microphone if that connect went
160+
// on to complete.
161+
final handshake = Completer<void>();
162+
container.wsConnector.connectGate = handshake.future;
163+
unawaited(room.connect(cloudUri, token).then((_) {}, onError: (_) {}));
164+
await Future<void>.delayed(const Duration(milliseconds: 10));
165+
unawaited(room.disconnect().then((_) {}, onError: (_) {}));
166+
await Future<void>.delayed(const Duration(milliseconds: 200));
167+
168+
expect(room.preConnectAudioBuffer.isRecording, isFalse);
169+
handshake.complete();
170+
});
171+
172+
test('pre-connect audio buffer is still reset when the connection drops', () async {
173+
final room = container.room;
174+
await container.connectRoom();
175+
room.preConnectAudioBuffer.markRecordingForTesting();
176+
177+
// The server asks the participant to leave, outside of any connect attempt.
178+
container.wsConnector.onData(
179+
lk_rtc.SignalResponse(
180+
leave: lk_rtc.LeaveRequest(
181+
action: lk_rtc.LeaveRequest_Action.DISCONNECT,
182+
reason: lk_models.DisconnectReason.ROOM_DELETED,
183+
),
184+
).writeToBuffer(),
185+
);
186+
await Future<void>.delayed(const Duration(milliseconds: 200));
187+
188+
expect(room.preConnectAudioBuffer.isRecording, isFalse);
189+
});
190+
}

‎test/mock/websocket_mock.dart‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,15 @@ class MockWebSocketConnector {
3131
NetworkOptions? networkOptions;
3232
Object? connectError;
3333

34+
/// When true, [connectError] is thrown once and then cleared, so the next
35+
/// connect succeeds. Models a first attempt that fails and a retry that gets
36+
/// through.
37+
bool connectErrorOnce = false;
38+
39+
/// When set, a connect waits for it before it answers. Models a socket
40+
/// handshake that is still in flight.
41+
Future<void>? connectGate;
42+
3443
/// Every message the SDK sent over any socket this connector opened.
3544
final List<List<int>> sentData = [];
3645

@@ -50,8 +59,13 @@ class MockWebSocketConnector {
5059
this.headers = headers;
5160
this.networkOptions = networkOptions;
5261

62+
await connectGate;
63+
5364
final error = connectError;
5465
if (error != null) {
66+
if (connectErrorOnce) {
67+
connectError = null;
68+
}
5569
throw error;
5670
}
5771

0 commit comments

Comments
 (0)