Skip to content

Commit f1c7450

Browse files
hiroshihorieclaude
andauthored
fix: make DataStreamError a LiveKitException (#1294)
## Problem `DataStreamError` was declared `implements Exception`, so it was not a `LiveKitException`, the base type the SDK documents for what it throws. An app that catches stream writes with `on LiveKitException` missed it. Since data streams v2 (#1166), native writes go through the Rust core. A write still in the core when the room is disposed fails with `DataStreamError(AbnormalEnd)`, which comes from the core's `InternalDataStreamException` via the catch-all in `toLKError`. The e2e scenario "Dispose during backpressured stream writes" expects every such write to fail with a `LiveKitException`, and found this. ## Change - `DataStreamError` now `implements LiveKitException` (the base class's constructor is private, so it can't be extended). `message` gets `@override`; `toString()` is unchanged. - The comment on `DataStreamErrorReason.AbnormalEnd` said "closed abnormally by remote participant". It now lists everything that maps to this reason: the sender leaving mid-stream, the local room disconnecting or being disposed, an I/O failure, and the FFI catch-all. The enum itself is unchanged. ## What I checked - **Catch sites in `lib/`:** none behaves differently. The only supertype check is `Checker.messageFor` (`error is LiveKitException`), and connection checks don't use data streams. Every other check names a specific type that `DataStreamError` doesn't match: `ConnectException`, `CertificatePinningException`, `NegotiationError`, `UnexpectedConnectionState`, `MediaConnectException`, `RpcError`, `PlatformException`, or `ffi.DataStreamException`. The data stream and RPC code catches errors without checking the type, then logs them or wraps them in `RpcError` from `e.toString()`. That string comes from `toString()`, which is unchanged. - **History:** #1166 (f38055a) is not in any release. `v2.13.2` was tagged from `release/2.13.2` and contains only a flutter_webrtc bump. Before #1166 on `main`, a write on a closed engine failed with `UnexpectedConnectionState` (#1267/#1268, also unreleased). In 2.13.x, by reading the code: a write waiting on the buffer polled forever, because dispose didn't announce engine closure yet. A write already sending hit the closed channel and failed with a `PlatformException`; the e2e case's note on #1277 agrees. So this is not a regression from a release. In 2.13.x `DataStreamError` was never a `LiveKitException` for any reason, readers included, so this is new behaviour for users. - **Web:** web still runs the Dart writer, which waits in `engine.waitForBufferStatusLow` and fails with `UnexpectedConnectionState`. That is already a `LiveKitException`. After this change both platforms fail the write with a `LiveKitException`, but the concrete types still differ: web gives `UnexpectedConnectionState`, native gives `DataStreamError(AbnormalEnd)`. On native, a write issued after the engine has closed still gets `UnexpectedConnectionState` from `_ensureOpen`, as before. - **API compatibility:** `dart-apitool diff` against `origin/main` (298cc62) reports "No breaking changes!", with one minor change: `Super Type "LiveKitException" added (CI04)`. The tool rates an added supertype as a minor change. The changeset is `patch` for now; minor vs patch is the owner's call. - **Pending changesets:** this changeset and the pending `.changes/buffer-wait-typed-error` read slightly inconsistently on native. That one says writes on a closed engine fail with `UnexpectedConnectionState`, which holds for a write issued after the engine closed. A write already in the core when the room is disposed gets `DataStreamError` (now a `LiveKitException`). Whoever writes the release notes should reconcile the two lines. I left the other changeset unchanged. ## Tests Added `writes cut off by disposing the room fail with a LiveKitException` to `test/core/data_stream_v2_test.dart`. It runs the real Rust core through the mock container: it starts 50 unawaited 30 KB writes on a byte stream, disposes the room, and checks that at least one write failed and that every failure is a `LiveKitException`. Without the change all 50 fail with `DataStreamError`, which is not a `LiveKitException`, and the test fails. With it, the test passed 5 times out of 5. Holding a write in a full send buffer doesn't reproduce this on native: the core's outgoing queue is unbounded, so writes return as soon as the core has queued them. `flutter analyze`, `flutter test`, `dart format`, `import_sorter`, and `check_version` all pass. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 298cc62 commit f1c7450

3 files changed

Lines changed: 26 additions & 2 deletions

File tree

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
patch type="fixed" "`DataStreamError` is now a `LiveKitException`, so `on LiveKitException` also catches data stream failures, such as a write cut off by disposing the room"

‎lib/src/data_stream/errors.dart‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,12 @@
1+
import '../exceptions.dart';
2+
13
enum DataStreamErrorReason {
24
// Unable to open a stream with the same ID more than once.
35
AlreadyOpened,
46

5-
// Stream closed abnormally by remote participant.
7+
// Stream ended before completing: the sender disconnected mid-stream, the local room was
8+
// disconnected or disposed, or sending or receiving failed. Also used for failures that map to no
9+
// more specific reason.
610
AbnormalEnd,
711

812
// Incoming chunk data could not be decoded.
@@ -24,8 +28,9 @@ enum DataStreamErrorReason {
2428
AlreadyClosed,
2529
}
2630

27-
class DataStreamError implements Exception {
31+
class DataStreamError implements LiveKitException {
2832
final DataStreamErrorReason reason;
33+
@override
2934
final String message;
3035

3136
DataStreamError({required this.reason, required this.message});

‎test/core/data_stream_v2_test.dart‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -582,6 +582,24 @@ void main() {
582582
expect(streamPackets().where((p) => !p.hasStreamTrailer()), isEmpty);
583583
});
584584

585+
test('writes cut off by disposing the room fail with a LiveKitException', () async {
586+
await container.simulateRemoteParticipantJoin('alice', clientProtocol: 2);
587+
final writer = await room.localParticipant!.streamBytes(StreamBytesOptions(topic: 'cut-off'));
588+
589+
// Not awaited: the room is disposed while these are still in the core, which fails them with
590+
// a DataStreamError. Apps catch the SDK's errors as LiveKitException, so it has to be one.
591+
final errors = <Object>[];
592+
final writes = [
593+
for (var i = 0; i < 50; i++)
594+
writer.write(Uint8List(30 * 1024)).then((_) {}, onError: (Object e) => errors.add(e)),
595+
];
596+
await room.dispose();
597+
await Future.wait(writes);
598+
599+
expect(errors, isNotEmpty, reason: 'no write was cut off, so there is nothing to check');
600+
expect(errors, everyElement(isA<LiveKitException>()));
601+
});
602+
585603
test('a stream packet still on its way in does not open a stream', () async {
586604
final ds = room.dataStreams as NativeDataStreams;
587605
var opened = 0;

0 commit comments

Comments
 (0)