Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .changes/preconnect-audio-survives-failover
Original file line number Diff line number Diff line change
@@ -0,0 +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)"
75 changes: 55 additions & 20 deletions lib/src/core/room.dart
Original file line number Diff line number Diff line change
Expand Up @@ -133,6 +133,19 @@ class Room extends DisposableChangeNotifier with EventsEmittable<RoomEvent> {
late EventsListener<SignalEvent> _signalListener;

RegionUrlProvider? _regionUrlProvider;

/// True while [connect] is running. A failed attempt tears the engine down
/// and reports a disconnect before [connect] retries another region, and
/// that cleanup must not throw away state the retry still needs.
bool _connectInProgress = false;

/// Lets tests install a provider with known regions, so a failover can be
/// exercised without reaching a real LiveKit Cloud endpoint.
@visibleForTesting
set regionUrlProviderForTesting(RegionUrlProvider? provider) {
_regionUrlProvider = provider;
}

String? _regionUrl;

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

var didConnect = false;
_connectInProgress = true;
try {
await engine.connect(
_regionUrl ?? url,
Expand All @@ -381,32 +395,43 @@ class Room extends DisposableChangeNotifier with EventsEmittable<RoomEvent> {
} catch (e) {
logger.warning('could not connect to $url $e');
if (_regionUrlProvider != null && canFailOverToAnotherRegion(e)) {
String? nextUrl;
try {
nextUrl = await _regionUrlProvider!.getNextBestRegionUrl();
} catch (error) {
if (error is ConnectException && (error.statusCode == 401)) {
String? nextUrl;
try {
nextUrl = await _regionUrlProvider!.getNextBestRegionUrl();
} catch (error) {
if (error is ConnectException && (error.statusCode == 401)) {
rethrow;
}
}
if (nextUrl != null) {
logger.fine('Initial connection failed with ConnectionError: $e. Retrying with another region: ${nextUrl}');
await engine.connect(
nextUrl,
token,
connectOptions: connectOptions,
roomOptions: effectiveRoomOptions,
fastConnectOptions: fastConnectOptions,
regionUrlProvider: _regionUrlProvider,
);
didConnect = true;
} else {
rethrow;
}
}
if (nextUrl != null) {
logger.fine('Initial connection failed with ConnectionError: $e. Retrying with another region: ${nextUrl}');
await engine.connect(
nextUrl,
token,
connectOptions: connectOptions,
roomOptions: effectiveRoomOptions,
fastConnectOptions: fastConnectOptions,
regionUrlProvider: _regionUrlProvider,
);
didConnect = true;
} else {
} catch (error) {
// The cleanup for the failed attempt left the pre-connect audio
// buffer recording for a retry, and no retry connected. Stop it
// with the error, the way withPreConnectAudio ends a failed
// operation, so the native recorder is stopped as well.
await preConnectAudioBuffer.stopRecording(withError: error);
await preConnectAudioBuffer.reset();
rethrow;
}
} else {
rethrow;
}
} finally {
_connectInProgress = false;
if (!didConnect) {
await NativeAudioManagement.stop();
}
Expand Down Expand Up @@ -676,7 +701,15 @@ class Room extends DisposableChangeNotifier with EventsEmittable<RoomEvent> {
// pending one when it starts.
if ((!engine.fullReconnectOnNext && !engine.isFullReconnectInProgress) ||
event.reason == DisconnectReason.clientInitiated) {
await _cleanUp(disposeLocalParticipant: false);
// A failed first attempt lands here before connect() retries another
// region. The pre-connect audio buffer has to survive that, or the
// retry connects without ever publishing the microphone. A disconnect
// the app asked for is not a retry: it resets the buffer as always, so
// nothing is published if that connect still completes.
await _cleanUp(
disposeLocalParticipant: false,
preservePreConnectAudio: _connectInProgress && event.reason != DisconnectReason.clientInitiated,
);
events.emit(RoomDisconnectedEvent(reason: event.reason));
notifyListeners();
}
Expand Down Expand Up @@ -1133,7 +1166,7 @@ class Room extends DisposableChangeNotifier with EventsEmittable<RoomEvent> {

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

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

_activeSpeakers.clear();

await preConnectAudioBuffer.reset();
if (!preservePreConnectAudio) {
await preConnectAudioBuffer.reset();
}

// clean up engine
await engine.cleanUp();
Expand Down
9 changes: 9 additions & 0 deletions lib/src/preconnect/pre_connect_audio_buffer.dart
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@

import 'dart:async';

import 'package:meta/meta.dart';
import 'package:uuid/uuid.dart';

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

/// Puts the buffer into its recording state without touching the
/// microphone, so tests can check what the Room does with a live buffer
/// where no audio device exists.
@visibleForTesting
void markRecordingForTesting() {
_isRecording = true;
}

/// Starts capturing audio into an in-memory buffer.
///
/// [timeout] controls how long to wait for an agent to become active. When the
Expand Down
9 changes: 8 additions & 1 deletion lib/src/support/http_client.dart
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,18 @@
// limitations under the License.

import 'package:http/http.dart' as http;
import 'package:meta/meta.dart';

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

http.Client createSdkHttpClient(NetworkOptions networkOptions) => impl.createSdkHttpClient(networkOptions);
/// Replaces the HTTP client the SDK builds, so tests can answer the requests
/// the SDK makes on its own, such as the validate call after a failed connect.
@visibleForTesting
http.Client Function(NetworkOptions networkOptions)? sdkHttpClientFactoryForTesting;

http.Client createSdkHttpClient(NetworkOptions networkOptions) =>
sdkHttpClientFactoryForTesting?.call(networkOptions) ?? impl.createSdkHttpClient(networkOptions);

Future<http.Response> sdkHttpGet(
Uri uri, {
Expand Down
190 changes: 190 additions & 0 deletions test/core/preconnect_failover_test.dart
Original file line number Diff line number Diff line change
@@ -0,0 +1,190 @@
// 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 'dart:async';

import 'package:flutter_test/flutter_test.dart';
import 'package:http/http.dart' as http;
import 'package:http/testing.dart';

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 'package:livekit_client/src/support/http_client.dart';
import 'package:livekit_client/src/support/region_url_provider.dart';
import 'package:livekit_client/src/support/websocket.dart';
import '../mock/e2e_container.dart';

const cloudUri = 'wss://test.livekit.cloud';
const token = 'token';

/// A provider that already knows its regions, so a failover never has to
/// fetch them. With no [regions] there is nowhere left to fail over to.
RegionUrlProvider providerWith(List<String> regions) =>
RegionUrlProvider(url: cloudUri, token: token)..setServerReportedRegions(
lk_rtc.RegionSettings()
..regions.addAll([
for (final region in regions)
lk_rtc.RegionInfo()
..region = region
..url = 'wss://$region.livekit.cloud',
]),
);

void main() {
TestWidgetsFlutterBinding.ensureInitialized();

late E2EContainer container;

// What the validate request answers after a failed socket connect. A 403 is
// one of the answers that makes connect() fail over to another region.
late int validateStatus;

setUp(() {
container = E2EContainer();
validateStatus = 403;
sdkHttpClientFactoryForTesting = (_) => MockClient(
(request) async => validateStatus == 200
? http.Response('success', 200)
: http.Response('project not allowed in this region.', validateStatus),
);
});

tearDown(() async {
sdkHttpClientFactoryForTesting = null;
await container.dispose();
});

test('pre-connect audio buffer survives a region failover on the first attempt', () async {
final room = container.room;

// Known regions, so a failed first attempt retries another region instead
// of failing the connect.
room.regionUrlProviderForTesting = providerWith(['other']);
room.preConnectAudioBuffer.markRecordingForTesting();

// The first socket connect fails, the retry gets through.
container.wsConnector.connectError = WebSocketException('first region down');
container.wsConnector.connectErrorOnce = true;
final connecting = room.connect(cloudUri, token);
await container.answerJoin();
await connecting;

expect(room.connectionState, ConnectionState.connected);
expect(container.wsConnector.uri.toString(), startsWith('wss://other.livekit.cloud'));
// The buffered microphone track is published from the join response, so
// the cleanup that runs for the failed attempt must leave the buffer alone.
expect(room.preConnectAudioBuffer.isRecording, isTrue);
});

test('pre-connect audio buffer survives a failover when only the socket is rejected', () async {
final room = container.room;
room.regionUrlProviderForTesting = providerWith(['other']);
room.preConnectAudioBuffer.markRecordingForTesting();

// The socket is refused while the validate request succeeds, so connect()
// fails over on the socket error itself.
validateStatus = 200;
container.wsConnector.connectError = WebSocketException('rejected');
container.wsConnector.connectErrorOnce = true;
final connecting = room.connect(cloudUri, token);
await container.answerJoin();
await connecting;

expect(room.connectionState, ConnectionState.connected);
expect(container.wsConnector.uri.toString(), startsWith('wss://other.livekit.cloud'));
expect(room.preConnectAudioBuffer.isRecording, isTrue);
});

test('pre-connect audio buffer is reset when connect fails with no failover', () async {
final room = container.room;
room.preConnectAudioBuffer.markRecordingForTesting();

// Not a LiveKit Cloud url, so there is no other region to try.
validateStatus = 401;
container.wsConnector.connectError = WebSocketException('down');
await expectLater(room.connect('wss://self.hosted.example', token), throwsA(isA<ConnectException>()));
await Future<void>.delayed(const Duration(milliseconds: 200));

expect(room.preConnectAudioBuffer.isRecording, isFalse);
});

test('pre-connect audio buffer is reset when the failover has no region left', () async {
final room = container.room;
room.regionUrlProviderForTesting = providerWith([]);
room.preConnectAudioBuffer.markRecordingForTesting();
// Stopped with the connect error, which is what also stops the native
// recorder, rather than with a plain reset.
final agentReady = expectLater(room.preConnectAudioBuffer.agentReadyFuture, throwsA(isA<ConnectException>()));

container.wsConnector.connectError = WebSocketException('down');
await expectLater(room.connect(cloudUri, token), throwsA(isA<ConnectException>()));
await agentReady;

expect(room.preConnectAudioBuffer.isRecording, isFalse);
});

test('pre-connect audio buffer is reset when the failover attempt fails too', () async {
final room = container.room;
room.regionUrlProviderForTesting = providerWith(['other']);
room.preConnectAudioBuffer.markRecordingForTesting();
final agentReady = expectLater(room.preConnectAudioBuffer.agentReadyFuture, throwsA(isA<ConnectException>()));

container.wsConnector.connectError = WebSocketException('down');
await expectLater(room.connect(cloudUri, token), throwsA(isA<ConnectException>()));
await agentReady;

expect(room.preConnectAudioBuffer.isRecording, isFalse);
});

test('pre-connect audio buffer is reset when disconnect() is called during connect', () async {
final room = container.room;
room.preConnectAudioBuffer.markRecordingForTesting();

// The socket handshake is still in flight when the app gives up. A buffer
// left recording here would publish the microphone if that connect went
// on to complete.
final handshake = Completer<void>();
container.wsConnector.connectGate = handshake.future;
unawaited(room.connect(cloudUri, token).then((_) {}, onError: (_) {}));
await Future<void>.delayed(const Duration(milliseconds: 10));
unawaited(room.disconnect().then((_) {}, onError: (_) {}));
await Future<void>.delayed(const Duration(milliseconds: 200));

expect(room.preConnectAudioBuffer.isRecording, isFalse);
handshake.complete();
});

test('pre-connect audio buffer is still reset when the connection drops', () async {
final room = container.room;
await container.connectRoom();
room.preConnectAudioBuffer.markRecordingForTesting();

// The server asks the participant to leave, outside of any connect attempt.
container.wsConnector.onData(
lk_rtc.SignalResponse(
leave: lk_rtc.LeaveRequest(
action: lk_rtc.LeaveRequest_Action.DISCONNECT,
reason: lk_models.DisconnectReason.ROOM_DELETED,
),
).writeToBuffer(),
);
await Future<void>.delayed(const Duration(milliseconds: 200));

expect(room.preConnectAudioBuffer.isRecording, isFalse);
});
}
14 changes: 14 additions & 0 deletions test/mock/websocket_mock.dart
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,15 @@ class MockWebSocketConnector {
NetworkOptions? networkOptions;
Object? connectError;

/// When true, [connectError] is thrown once and then cleared, so the next
/// connect succeeds. Models a first attempt that fails and a retry that gets
/// through.
bool connectErrorOnce = false;

/// When set, a connect waits for it before it answers. Models a socket
/// handshake that is still in flight.
Future<void>? connectGate;

/// Every message the SDK sent over any socket this connector opened.
final List<List<int>> sentData = [];

Expand All @@ -50,8 +59,13 @@ class MockWebSocketConnector {
this.headers = headers;
this.networkOptions = networkOptions;

await connectGate;

final error = connectError;
if (error != null) {
if (connectErrorOnce) {
connectError = null;
}
throw error;
}

Expand Down
Loading