Skip to content

Connections and Transports

Se.Cherkasov edited this page Aug 23, 2026 · 1 revision

Connections and transports

English · Русский

The contract

Everything the UI can connect to hides behind one interface in commonMain:

interface SshTransport {
    suspend fun connect(target: SshTarget, auth: SshAuth): SshConnection
}

SshTarget carries the host, port, user, connectionType, an optional jump chain, the keep-alive cadence, an optional container spec, and an optional shellCommand that replaces the login shell on the interactive channel.

Routing

RoutingTransport (jvmShared) dispatches on connectionType:

flowchart TD
  RT[RoutingTransport] -->|SSH| SSHJ[SshjTransport]
  RT -->|MOSH| M[MoshTransport] --> SSHJ
  RT -->|CONTAINER| C[ContainerTransport] --> SSHJ
  RT -->|TELNET| T[TelnetTransport]
  RT -->|SERIAL| SR[SerialTransport]
  RT -->|LOCAL| L[LocalShellTransport]
  RT -->|VNC / RDP| X[not an SSH transport — VncTransport / RdpTransport]
Loading

Mosh and container exec bootstrap over the same injected SSH transport, so host-key trust and ProxyJump behave identically for them. Telnet, serial and local are stateless and default-constructed, and can be swapped in tests.

Shell channels

Shape Abstraction
"Just a stream" (telnet, serial) ssh/StreamOnlyConnection
Blocking read loop of a shell channel ssh/StreamShellChannel
SSH channel proper ssh/SshjShellChannel
Mosh's own framing mosh/MoshShellChannel

Port forwards live in ssh/ForwardState and SshjForwards; the SOCKS5 server behind dynamic forwarding is ssh/Socks5.kt.

Jump chains

SshJump is one resolved hop with its own auth and its own jump — a linked list resolved outermost-first, exactly like ssh -J a,b. Host-key verification runs for every hop under its own (host, port). The UI resolves the chain at connect time and fails the connection on a dangling id, a non-SSH jump, a secretless jump or a cycle, rather than silently going direct.

Host trust

trust/HostTrust is the one shape for "ask the user to vouch for a host's identity", used by both the SSH host key and the RDP certificate:

  • HostTrustPrompt — suspending, implemented by the UI;
  • HostTrustDecider — synchronous, what a handshake can call;
  • trust/asDecider (jvmShared) bridges the two.

Trust decisions are stored in the vault (VaultKnownHostsStore, VaultTrustedCaStore, FileRdpCertificateStore). A probe transport is deliberately separate: its verifier does not add a key to known hosts, so testing a connection never establishes trust.

Interactive prompts

A connection sometimes has to ask a question mid-handshake — a keyboard-interactive 2FA code, a host-key decision. Both go through ui/design/PromptQueue, which is a turnstile: two hosts asking at once queue instead of overwriting each other's dialog, the deadline starts when the question reaches the screen, and an answer is bound to the question it was given for.

Sessions above the transport

ui/connection/ConnectionController owns connect, reconnect and teardown; ui/session owns tabs, panes and broadcast. Reconnect applies to types where it is meaningful (carriedBySsh) and is deliberately not applied to Mosh, which survives outages itself — reconnecting there would open a second remote session behind the user's back.

Concurrency rules that apply here

From docs/coding-guidelines.md §3, each written after a defect:

  • never swallow CancellationException around suspend code — cancellation must not masquerade as a network error;
  • reset guard flags and busy state in finally, or a cancelled coroutine wedges the feature;
  • assignment to shared state happens under the same mutex as the check that guarded it (a double connect once leaked a Ktor client);
  • a long-lived connection must read incoming frames — a write-only WebSocket handler misses Close and hangs.

Clone this wiki locally