Skip to content

feat: add ConnectionCheck utility for connection diagnostics#1134

Open
kNoAPP wants to merge 6 commits into
livekit:mainfrom
kNoAPP:feat/connection-check
Open

feat: add ConnectionCheck utility for connection diagnostics#1134
kNoAPP wants to merge 6 commits into
livekit:mainfrom
kNoAPP:feat/connection-check

Conversation

@kNoAPP

@kNoAPP kNoAPP commented Jul 20, 2026

Copy link
Copy Markdown
Contributor

Summary

This PR ports the ConnectionCheck connection-diagnostics utility from client-sdk-js to Dart, the same checks that power livekit.io/connection-test. Flutter apps can now run structured preflight diagnostics proactively (at app start) or reactively (when room.connect() fails) to determine why a connection cannot be established (firewall, VPN, blocked TURN, etc.), instead of asking users to reproduce on web.

Ref: Diagnosing Connection Errors with Connection Test Utility

Demo

rtc_connection_check

API

final connectionCheck = ConnectionCheck(url, token);
final listener = connectionCheck.createListener();
listener.on<ConnectionCheckUpdateEvent>((event) {
  print('${event.info.name}: ${event.info.status.name}');
});

// recommended minimum set
await connectionCheck.checkWebsocket();
await connectionCheck.checkWebRTC();
await connectionCheck.checkTURN();

// additional checks
await connectionCheck.checkReconnect();
await connectionCheck.checkPublishAudio();
await connectionCheck.checkPublishVideo();
await connectionCheck.checkConnectionProtocol();
await connectionCheck.checkCloudRegion();

print('all checks passed: ${connectionCheck.isSuccess}');
await listener.dispose();
await connectionCheck.dispose();

Testing

  • flutter test: 364 passing (20 new tests covering the Checker base lifecycle, ConnectionCheck orchestration/eventing, ICE candidate parsing, and WebSocketCheck against the mock WebSocket connector).
  • flutter analyze, dart format, import_sorter, check_version passing
  • Manually tested web, iOS, Android

Example

example/lib/pages/connection_check.dart adds a "Connection Check" page (launched from the connect screen) that runs all checks and displays per-check status + logs.

kNoAPP added 2 commits July 20, 2026 08:20
Port the ConnectionCheck (preflight) utility from client-sdk-js
(src/connectionHelper) to Dart, so Flutter apps can diagnose why a
connection to a LiveKit server fails (firewall, VPN, blocked TURN, etc.)
either proactively at app start or reactively on a connection error.

Includes all 8 checks from the JS implementation: websocket, WebRTC,
TURN, reconnect, publish audio, publish video, connection protocol
(UDP vs TCP) and Cloud region, exposed via a ConnectionCheck class
with per-check structured results (status, logs, data) and update
events using the SDK's EventsEmittable pattern.

Browser-only techniques were adapted for Flutter (documented in
dartdoc): silence detection via media-source stats instead of
WebAudio, camera frame verification via framesSent instead of canvas
sampling, a camera track instead of an animated canvas track for the
protocol comparison, and qualityLimitationDurations approximated by
sampling qualityLimitationReason.

Also adds a Connection Check page to the example app, unit tests for
the checker lifecycle, orchestration, ICE candidate parsing and the
websocket check, plus a README section.
@kNoAPP
kNoAPP marked this pull request as ready for review July 20, 2026 16:27

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 1 additional finding.

Open in Devin Review

devin-ai-integration[bot]

This comment was marked as resolved.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant