A desktop SSH client can show an interactive shell and a remote file browser for the same host. Their lifetimes are different: a user may close Files, cancel an upload, or switch hosts while keeping a shell open.
That creates a useful design question: which component owns the connection that a cancellation is allowed to close?
I'm the maintainer of Netrix, a desktop terminal client. This article examines the SFTP connection lifecycle in its public 0.3.0-beta.8 source snapshot. The implementation is in Rust, using Tokio and russh.
SSH channels and connection ownership
SSH supports multiple channels within one encrypted connection. A shell and an SFTP subsystem can use different channels on a shared connection; the protocol does not require a separate connection for every feature. RFC 4254 describes the channel mechanism.
Sharing can avoid additional connection setup and authentication. It also means the application needs a clear owner for the shared transport. Closing one channel and disconnecting the entire SSH connection have different consequences.
Netrix gives SFTP its own SSH transports. The terminal manager retains ownership of interactive terminal connections, while the SFTP manager owns file-operation connections:
Saved host profile and credential loading
|
Shared host-key trust
|
+-------+-------+
| |
Terminal manager SFTP manager
| |
SSH connection A SSH connection B
| |
Shell channel SFTP subsystem
An SFTP failure can therefore discard its own transport without asking the terminal manager to reset a shell. This is a lifecycle boundary: both features still depend on the same backend process, network and remote server.
The Files view has a connection lifecycle separate from terminal tabs. Identifying details in this screenshot are masked.
Bound the cost of isolation
Separate transports have a cost: more sockets, authentication work and server-side connections. Opening a new SSH connection for every directory click would make that cost visible quickly.
The SFTP connection manager uses leases and bounded reuse. A lease gives one operation exclusive access to an SFTP connection. A healthy connection can return to the idle pool when the operation finishes.
The current implementation has these bounds:
| Resource | Limit |
|---|---|
| Concurrent SFTP leases | 4 |
| Retained idle connections | 8 |
| Idle connection lifetime | 60 seconds |
| Idle cleanup interval | 15 seconds |
The four-lease limit is a concurrency limit, not a claim that the application can only hold four SSH sockets in total. Idle SFTP transports and interactive terminals have separate lifetimes.
Setup also has a deadline covering the wait for a pool slot, connection establishment, authentication and subsystem initialization. A stalled authentication attempt should not reserve work indefinitely. Failed or timed-out operations do not return their connection as healthy.
The disconnect race is more interesting than the happy path
Consider this sequence:
- A directory listing borrows a connection.
- The user disconnects that saved host's Files session.
- The disconnect handler removes its idle connections.
- The listing finishes and tries to return its borrowed connection.
If disconnect only clears the idle map, step four can repopulate it. The UI says disconnected, but the old connection has quietly become reusable again.
Netrix associates leases with a per-profile cancellation scope. Disconnect cancels that scope and removes the profile's idle entries. The lease-return path checks the scope while holding the pool-state lock; a lease from a cancelled lifetime cannot re-enter the pool.
The saved profile ID matters too. Two profiles can point at the same address and port while representing different connection choices. Disconnecting one profile should not invalidate the other's pool lifetime. A later connection for the disconnected profile gets a new scope.
This pattern applies beyond SSH: when async work can outlive a view or session, cache eviction alone may not invalidate work already in flight.
Keep trust shared across the boundary
Transport isolation should not create competing answers to “is this the same server?” Terminal and SFTP connections share the application's host-key trust model.
Pool reuse also depends on more than the endpoint. Its key includes the saved profile, authentication inputs, host-key policy and current known-host entry, represented by a process-salted SHA-256 digest. A changed credential or trust entry produces a different reuse key. This digest is a cache identity mechanism; it does not replace credential-vault encryption or SSH host-key verification.
Cancellation does not undo a remote write
Independent transports make it clearer which connection can be closed. They do not make a mutation transactional across the network.
For uploads, the implementation writes a temporary sibling file, checks completion, then commits through a rename. The transfer registry serializes cancellation with entry into the commit phase. Once the rename is starting, cancellation returns a conflict instead of promising rollback.
A lost rename reply is another important case: the server may have committed even though the client cannot confirm success. The operation reports failure with instructions to inspect the destination before retrying. It does not automatically replay the write.
The SFTP implementation notes describe the cleanup rules and limits. Cleanup can leave a temporary file when the server is unreachable. Recursive directory transfer, synchronization and resume after application restart are not implemented.
Test the lifetime boundaries
A useful verification plan should include more than a successful upload:
- Disconnect while a directory response is deliberately delayed, then confirm the late lease cannot revive the pool.
- Use two profiles for the same endpoint and disconnect only one.
- Stall SSH authentication and disconnect during setup.
- Cancel an upload before commit, and separately exercise cancellation at the commit boundary.
- Inject an SFTP failure while a terminal remains connected and check both lifecycles independently.
The repository documents an opt-in local SSH/SFTP smoke fixture for several of these cases, alongside packet, API and cancellation tests. Those checks still need complementary testing against real server implementations and the native file-saving UI.
The design choice is about ownership: give each workflow a clear connection lifetime, preserve shared trust checks, and make cancellation semantics explicit all the way through to the remote commit.
AI disclosure: This article was drafted by an AI assistant from Netrix's public source code and documentation. The screenshots show the application with identifying details masked.

Top comments (0)