Skip to content

Add live stream connection health tracking and UI TCP timeout warnings - #147

Open
sappelhoff wants to merge 3 commits into
labstreaminglayer:masterfrom
sappelhoff:feat/stream-connection-diagnostics
Open

sappelhoff wants to merge 3 commits into
labstreaminglayer:masterfrom
sappelhoff:feat/stream-connection-diagnostics

Conversation

@sappelhoff

@sappelhoff sappelhoff commented Aug 26, 2026

Copy link
Copy Markdown
Contributor

Problem

When stream discovery succeeds over UDP broadcast but establishing the TCP data connection fails or times out (e.g. due to Windows Firewall, multi-NIC/VPN routing like WireGuard, or unreachable remote ports), in->open_stream() caught lsl::timeout_error and silently proceeded to record. The user received no visual feedback in the GUI, resulting in empty ~40 KB files containing only XML stream headers and zero sample chunks.

Solution

  1. Stream Telemetry: Added a thread-safe StreamTelemetry tracker in recording to monitor per-stream TCP connection status and sample counts.
  2. TCP Timeout Flagging: Flag connection_failed = true when in->open_stream() encounters a timeout error during stream subscription.
  3. UI Warning: In MainWindow::statusUpdate(), surface an immediate warning banner in the status bar if any stream's TCP connection failed (or is offline/missing), alerting the experimenter in real-time.

UI Preview

State Preview
Normal Recording Normal Recording
Recording to sub-001.xdf (00:02:15; 1420kb)
Connection Warning (Timeout / Offline) Warning
Recording to sub-001.xdf (00:02:15; 40kb) | WARNING: Cannot connect to BioSemi (TCP timeout)

Verification

  • Tested locally and in CI across Windows, Ubuntu, and macOS.
  • Verified that when a stream outlet is dropped/unreachable at start, the UI immediately displays the connection warning banner in the status bar while continuing to record any other valid streams.

@sappelhoff
sappelhoff force-pushed the feat/stream-connection-diagnostics branch from eec86a3 to 3b16f21 Compare August 27, 2026 08:24
@cboulay

cboulay commented Sep 20, 2026

Copy link
Copy Markdown
Contributor

The connection warning is useful, but I recommend changes before merging:

  1. Clear the TCP failure state after recovery. connection_failed is set when the initial open_stream() times out, but never reset when the connection subsequently succeeds and samples arrive. A healthy recording then keeps displaying "Cannot connect ... (TCP timeout)" for the remainder of the recording. Please model recovery explicitly and test a delayed connection that eventually starts producing samples.

  2. Use live recording state for offline warnings. statusUpdate() appends every entry in missingStreams, but that collection is updated by GUI refresh, not by record_from_query_results() when a watched stream appears. A stream missing at Start can later be discovered and recorded while the banner still says it is offline. Reconcile watched-stream state with recording telemetry and test the missing-at-start -> recording transition without a manual refresh.

This PR includes all of #146's changes, so the shutdown and validation findings posted there also apply. I suggest fixing #146 first, then rebasing this PR to make the telemetry/UI changes independently reviewable.

Review scope: source inspection; I did not run an end-to-end GUI/network recovery test.

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.

2 participants