Skip to content

fix(ssh): wait for terminal WebSocket readiness before connecting - #1

Merged
LukeGus merged 1 commit into
Termix-SSH:mainfrom
AdamClaassens:fix/terminal-websocket-readiness-race
Oct 5, 2026
Merged

LukeGus merged 1 commit into
Termix-SSH:mainfrom
AdamClaassens:fix/terminal-websocket-readiness-race

Conversation

@AdamClaassens

Copy link
Copy Markdown
Contributor

Problem

termix ssh <hostId> can time out with:

Timed out waiting for connected or passphrase_required or sessionAttached.

This can occur even when:

  • the same host connects successfully through the Termix web terminal;
  • termix exec works against the same host;
  • the terminal WebSocket itself connects successfully.

In the reproduced failure, the server logged the terminal WebSocket connection being established but did not proceed to host resolution or SSH connection before the CLI timed out.

Cause

TerminalSocket.open() resolves when the WebSocket transport reaches the open state.

termix ssh then immediately sends connectToHost.

The Termix server performs asynchronous authentication and data-key initialization before its terminal application message handler is ready. On sufficiently fast connections, the initial connectToHost frame can arrive before the server is ready to process terminal messages.

Fix

Add TerminalSocket.waitUntilReady() and call it from the interactive SSH path after opening the WebSocket but before sending connectToHost.

The readiness check uses the terminal protocol's existing ping / pong messages.

The implementation reuses the existing:

  • requestTimeoutMs
  • waitFor()
  • send()
  • WebSocket close/error handling

TerminalSocket.open() retains its existing transport-only semantics.

Tests

Added regression coverage for:

  • terminal handler immediately ready;
  • terminal handler becoming ready after a delay;
  • terminal handler never becoming ready.

Full project verification passes:

Test Files  14 passed (14)
Tests       162 passed (162)
All smoke checks passed.

Formatting, ESLint, TypeScript type checking, unit tests, and package smoke tests all pass.

Integration verification

Reproduced against Termix Server 2.8.0.

Before the change:

Terminal WebSocket connection established
[60 second timeout]
Terminal WebSocket disconnected

The same host worked through both the Termix web terminal and termix exec.

After the change, a locally built standalone CLI successfully opened the interactive SSH session:

Connected to <user>@<host>.
<remote prompt>

This keeps readiness handling scoped to the interactive terminal path without changing the semantics of TerminalSocket.open().

@LukeGus
LukeGus merged commit 9beb584 into Termix-SSH:main Oct 5, 2026
1 check passed
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