feat: Resume session upon disconnect

[billchurch]

@willnode opened PR #376 with a great idea, but due to the ongoing refactoring, I won't be able to use it as is. I would like to document the use case here for later inclusion.

I will soon be moving my current development branch into main, and I'll give you a heads up when I do, if you want to try and work this back in, it would be appreciated.

For more details, see #368

Thanks.

[willnode]

No problem, take your time and hopefully we can discuss a way to get it merged on main 👍

[willnode]

Hi @billchurch I would like to tackle this on new rebase, any comments the original idea?

[fondoger]

How about scenarios with tmux? It can preserve all terminal output when you resume a tmux session.

[willnode]

tmux is good workaround but it doesn't handle more complex scenario, like timing out idle/background session. It is also an extra command which user always have to type and remember.

[billchurch]

@willnode appreciate the offer to take this on. Before you invest time in a rebase, I'd like to align on the design first — session resumption touches several sensitive parts of the architecture (auth, SSH stream lifecycle, socket reconnection), so I want to make sure we're on the same page on approach before code lands.

Could you walk me through what you're thinking? A few specific things I'd like to understand:

1. Resumption boundary — what's being preserved on disconnect? Just the SSH session/PTY on the server side, or also scrollback/terminal state on the client? Where does the buffer live and for how long?

2. Identity & auth on resume — how does a reconnecting client prove it owns the prior session? Cookie? Signed token? What stops session A from resuming session B if they guess an ID? How does this interact with our existing auth modes (basic, POST, manual)?

3. Lifetime & cleanup — idle timeout for orphaned sessions, max concurrent suspended sessions per user, memory/PTY ceiling. What happens on server restart?

4. SSH side — keeping the SSH2 ClientChannel alive without an attached websocket: how do we handle backpressure and output that arrives while no client is connected? Bounded ring buffer?

5. Scope — new features in this project are always opt-in by default. We try to maintain a stable contract with existing users: upgrading should not change observed behavior unless they explicitly turn something on. Obvious breaking changes happen occasionally, but functional changes should be gated behind a config flag (and/or per-connection override) so existing deployments are unaffected. Please design with that constraint up front — it tends to be much harder to retrofit later.

6. Tests — what does the integration test story look like? We'd want coverage for: clean reconnect, expired session, auth mismatch on resume, multiple disconnect/reconnect cycles, server-side cleanup.

A short design sketch (a paragraph or two per point above, plus a rough sequence diagram for the disconnect/reconnect flow) would be ideal before any code. Once we agree on the shape, a small PR against a feature branch is the right next step rather than a full rebase.

Re: tmux as a workaround — agree it doesn't cover all cases (idle timeout, no-shell-access scenarios), but it's worth noting in the design as the "do nothing" alternative so we can be explicit about what value the feature adds.

[willnode]

@billchurch Thanks for replying. Before I replied, I would like to thank you for maintaining this beautiful software. I use it for domcloud.co which is a hosting service I own and all stack software is completely open except billing part. With that in mind:

1. When client disconnect it will ignore the SSH() object in the global SSH map thus the connection to target SSH remain intact. That's only what preserved. When user reconnecting the JS client will send enter \n key. This is enough to redraw any TUI object or shell prompt.
2. When connecting to server it will check based on this algo:

  const mapKey = [socket.request.sessionID, socket.request.session.username, socket.request.session.ssh.host].join('/')
  var connMap = sshMap.get(mapKey);
  if (!connMap) {
    connMap = setupNewConnection(socket); // new ssh session
    sshMap.set(mapKey, connMap);
  } else {
    connMap.changeSocket(socket); // see below
  } 

I admit it's not the best security as attacker will only have to guess session ID when target username + host is known which is not coming from a hardered random seed but it's enough for my usecase. Also session is saved to localStorage, so the user cannot have multiple session from the same browser window but it can spawn another one from incognito.
3. It is not implemented because it will add more complexity. In my case I let my server balancer (nginx plus other scripts) restart the webssh server if lived more than 3 hour. That also disconnect any existing SSH connection.
4. Afaik socket discards any stream if disconnected so there's no backbuffer. The code for client reconnection is

changeSocket: (newSocket) => {
      if (!socket.disconnected) {
        socket.disconnect();
      }
      socket = newSocket;

      // to display after resuming connection
      if (login && stream) {
        handshake();
        stream.write("\n");
      } 
    }

5. Yes I expect this is opt-in. There are gotchas user need to read when using this feature.
6. I never write integration test in my last PoC but maybe your new code have one. In that case I would want:
   • connecting new then reconnecting with same session ID should close the existing connection
   • the ssh connection remain intact when socket closed
   • connection to SSH server dropped when user say exit or clicking the reconnect button

We might need to discuss a bit about question 3, maybe duration based expiration would be good, plus maximum connection pool (if there isn't any).

I agree on incremental approah. I actually have other things going on so incremental PR can be made. Maybe the step is

1. Add the configuration
2. Server-client reconnect implementation
3. Server-SSH pool cleanup
4. Client side (add reconnect button and state)