@mmmbuto/nexuscrew 0.9.13 → 0.9.15

package/lib/ws/bridge.js

@@ -1,4 +1,5 @@
 'use strict';
+const crypto = require('node:crypto');
 // Bridges ONE WebSocket to ONE PTY attach. Dependencies are injectable for tests.
 // Hardening: close on protocol violation, no 2nd attach, clamp cols/rows,
 // validated session, backpressure cutoff, errors as JSON with a code.
@@ -11,19 +12,138 @@ function clamp(n, lo, hi, def) {
 }
 
 const ATTACH_TIMEOUT_MS = 15000;
+// Mobile handovers and tunnel renegotiation can last longer than a LAN retry.
+// Thirty seconds is finite but configurable, so a small host can tune the
+// trade-off without making the suspended PTY lifetime unbounded.
+const PTY_GRACE_MS = 30000;
+const PTY_GRACE_MAX_SESSIONS = 8;
+// No PTY output is buffered while detached; this bounds the retained record,
+// rather than pretending a stale output buffer is a current terminal screen.
+const PTY_GRACE_RECORD_BYTES = 1024;
+const PTY_GRACE_MAX_MEMORY_BYTES = PTY_GRACE_MAX_SESSIONS * PTY_GRACE_RECORD_BYTES;
+
+function createPtyGraceStore({
+  graceMs = PTY_GRACE_MS,
+  maxSessions = PTY_GRACE_MAX_SESSIONS,
+  maxMemoryBytes = PTY_GRACE_MAX_MEMORY_BYTES,
+  recordBytes = PTY_GRACE_RECORD_BYTES,
+  randomBytes = crypto.randomBytes,
+} = {}) {
+  const suspended = new Map();
+  const sessionLimit = Math.max(1, Math.floor(Number(maxSessions) || PTY_GRACE_MAX_SESSIONS));
+  const memoryLimit = Math.max(1, Math.floor(Number(maxMemoryBytes) || PTY_GRACE_MAX_MEMORY_BYTES));
+  const retainedRecordBytes = Math.max(1, Math.floor(Number(recordBytes) || PTY_GRACE_RECORD_BYTES));
+  let memoryBytes = 0;
+
+  const clearRecordTimer = (record) => {
+    if (record.graceTimer) clearTimeout(record.graceTimer);
+    record.graceTimer = null;
+  };
+
+  const issueToken = (record) => {
+    if (!record.resumeToken) record.resumeToken = randomBytes(32).toString('base64url');
+    return record.resumeToken;
+  };
+
+  const releaseRecord = (token, record) => {
+    if (suspended.get(token) !== record) return false;
+    suspended.delete(token);
+    memoryBytes = Math.max(0, memoryBytes - record.graceBytes);
+    return true;
+  };
+
+  const suspend = (record) => {
+    if (!record || record.ended) return null;
+    const token = issueToken(record);
+    if (!suspended.has(token)
+      && (suspended.size >= sessionLimit || memoryBytes + retainedRecordBytes > memoryLimit)) return null;
+    clearRecordTimer(record);
+    if (!suspended.has(token)) {
+      record.graceBytes = retainedRecordBytes;
+      memoryBytes += retainedRecordBytes;
+    }
+    suspended.set(token, record);
+    record.graceTimer = setTimeout(() => {
+      if (suspended.get(token) !== record) return;
+      releaseRecord(token, record);
+      record.graceTimer = null;
+      record.graceExpired = true;
+      try { record.pty.kill(); } catch (_) {}
+    }, graceMs);
+    if (typeof record.graceTimer.unref === 'function') record.graceTimer.unref();
+    return token;
+  };
+
+  const resume = (token, session) => {
+    if (!token || typeof session !== 'string') return null;
+    const record = suspended.get(token);
+    if (!record || record.ended || record.session !== session || record.ws) return null;
+    releaseRecord(token, record);
+    clearRecordTimer(record);
+    return record;
+  };
+
+  const resumeEnded = (token, session) => {
+    if (!token || typeof session !== 'string') return null;
+    const record = suspended.get(token);
+    if (!record || !record.ended || record.session !== session || record.ws) return null;
+    releaseRecord(token, record);
+    clearRecordTimer(record);
+    return record;
+  };
+
+  const close = () => {
+    for (const record of suspended.values()) {
+      clearRecordTimer(record);
+      try { record.pty.kill(); } catch (_) {}
+    }
+    suspended.clear();
+    memoryBytes = 0;
+  };
+
+  return {
+    issueToken,
+    suspend,
+    resume,
+    resumeEnded,
+    close,
+    size: () => suspended.size,
+    memoryBytes: () => memoryBytes,
+    limits: () => ({ maxSessions: sessionLimit, maxMemoryBytes: memoryLimit }),
+  };
+}
+
+function sendJson(ws, value) {
+  try { ws.send(JSON.stringify(value)); } catch (_) {}
+}
 
 function bindWs(ws, deps) {
-  const { openAttach, verifyToken, isValidSession = () => true, runAction = () => false, countClients = () => 0, defaults = {}, onAttach = () => {} } = deps;
-  let pty = null;
+  const { openAttach, verifyToken, isValidSession = () => true, runAction = () => false, countClients = () => 0, defaults = {}, onAttach = () => {}, ptyGrace = null } = deps;
+  let record = null;
   let attached = false;
   let session = null;
 
+  const detach = () => {
+    if (!record || record.ws !== ws) return;
+    record.ws = null;
+    if (record.ended) return;
+    if (!ptyGrace) {
+      try { record.pty.kill(); } catch (_) {}
+      return;
+    }
+    if (!ptyGrace.suspend(record)) {
+      // A bounded host refuses another suspended PTY instead of exceeding its
+      // explicit process/memory budget.
+      try { record.pty.kill(); } catch (_) {}
+    }
+  };
+
   function fail(code, reason) {
     // Si spegne anche la scadenza pre-attach: un frame rifiutato (token o
     // handshake non validi) chiude gia' il socket, e lasciare il timer vivo
     // fino al close event tiene in piedi un handle senza scopo.
     clearAttachTimer();
-    try { ws.send(JSON.stringify({ type: 'error', reason })); } catch (_) {}
+    sendJson(ws, { type: 'error', reason });
     try { ws.close(code, reason); } catch (_) {}
   }
 
@@ -51,25 +171,53 @@ function bindWs(ws, deps) {
       try { msg = JSON.parse(data.toString()); } catch (_) { return fail(1002, 'bad handshake'); }
       if (msg.type !== 'attach') return fail(1002, 'expected attach');
       if (!verifyToken(msg.token)) return fail(4401, 'bad token');
-      if (!isValidSession(msg.session)) return fail(4404, 'no such session');
+
+      // Authorization precedes every live-PTY resume. A terminated record is
+      // different: its only remaining purpose is to deliver the late exit
+      // outcome, so it has an explicit, non-attach path below.
+      if (!isValidSession(msg.session)) {
+        const ended = ptyGrace && ptyGrace.resumeEnded(msg.reconnectToken, msg.session);
+        if (ended) {
+          clearAttachTimer();
+          sendJson(ws, { type: 'exit', code: ended.exitCode });
+          try { ws.close(1000, 'exit'); } catch (_) {}
+          return;
+        }
+        return fail(4404, 'no such session');
+      }
+
+      // The capability is bound to the authenticated session and can resume
+      // only a still-live PTY. It is never an alternative to isValidSession.
+      const resumed = ptyGrace && ptyGrace.resume(msg.reconnectToken, msg.session);
+      if (resumed) {
+        clearAttachTimer();
+        record = resumed;
+        record.ws = ws;
+        record.readonly = record.readonly || !!msg.readonly;
+        attached = true;
+        session = record.session;
+        onAttach(session, ws);
+        sendJson(ws, { type: 'attached', reconnectToken: record.resumeToken });
+        return;
+      }
       attached = true;
       clearAttachTimer();
       session = msg.session;
-      onAttach(session, ws);
       // Resize default: when nobody else is attached, drive the session size so a
       // small phone gets a usable (non-clipped) view and clean line editing. When a
       // real terminal is already attached, default to ignore-size so we don't shrink
       // its window. An explicit takeSize from the client always wins.
-      const takeSize = msg.takeSize !== undefined
-        ? !!msg.takeSize
-        : countClients(msg.session) === 0;
       // "Segue il focus": garantisce window-size latest sulla sessione (il
       // client usato piu' di recente ne guida la geometria). Fire-and-forget.
       try {
         require('node:child_process').execFile(defaults.tmuxBin || 'tmux',
           ['set-option', '-t', `=${msg.session}:`, 'window-size', 'latest'], () => {});
       } catch (_) {}
-      pty = openAttach(msg.session, {
+      const takeSize = msg.takeSize !== undefined
+        ? !!msg.takeSize
+        : countClients(msg.session) === 0;
+      record = {
+        pty: openAttach(msg.session, {
         // readonlyDefault del server e' un PAVIMENTO, non un default: se il server
         // e' READONLY nessun client puo' declassarlo (msg.readonly:false non deve
         // vincere). Il client puo' solo AGGIUNGERE restrizione (attach read-only
@@ -80,34 +228,52 @@ function bindWs(ws, deps) {
         cols: clamp(msg.cols, 20, 300, 80),
         rows: clamp(msg.rows, 5, 120, 24),
         tmuxBin: defaults.tmuxBin || 'tmux',
+        }),
+        ws,
+        session: msg.session,
+        readonly: defaults.readonlyDefault === true || !!msg.readonly,
+        takeSize,
+        ended: false,
+        exitCode: undefined,
+        resumeToken: null,
+        graceTimer: null,
+        graceExpired: false,
+      };
+      // The token is issued for this record, not for an arbitrary caller.
+      if (ptyGrace) record.resumeToken = ptyGrace.issueToken(record);
+      onAttach(session, ws);
+      record.pty.onData((d) => {
+        if (!record.ws) return;
+        try { record.ws.send(Buffer.from(d), { binary: true }); } catch (_) { return; }
+        if ((record.ws.bufferedAmount || 0) > MAX_BUFFERED) fail(1011, 'backpressure');
       });
-      pty.onData((d) => {
-        try { ws.send(Buffer.from(d), { binary: true }); } catch (_) { return; }
-        if ((ws.bufferedAmount || 0) > MAX_BUFFERED) fail(1011, 'backpressure');
-      });
-      pty.onExit((info) => {
-        try { ws.send(JSON.stringify({ type: 'exit', code: info && info.exitCode })); } catch (_) {}
-        try { ws.close(1000, 'exit'); } catch (_) {}
+      record.pty.onExit((info) => {
+        record.ended = true;
+        record.exitCode = info && info.exitCode;
+        if (!record.ws) return;
+        sendJson(record.ws, { type: 'exit', code: record.exitCode });
+        try { record.ws.close(1000, 'exit'); } catch (_) {}
       });
+      sendJson(ws, { type: 'attached', reconnectToken: record.resumeToken });
       return;
     }
     // dopo l'attach
-    if (isBinary) { pty.write(data); return; }
+    if (isBinary) { if (!record.readonly) record.pty.write(data); return; }
     let msg;
     try { msg = JSON.parse(data.toString()); } catch (_) { return; }
     if (msg.type === 'attach') return fail(1002, 'already attached'); // no 2nd attach
-    if (msg.type === 'resize') pty.resize(clamp(msg.cols, 20, 300, 80), clamp(msg.rows, 5, 120, 24));
+    if (msg.type === 'resize') record.pty.resize(clamp(msg.cols, 20, 300, 80), clamp(msg.rows, 5, 120, 24));
     // focus: il tile che prende il focus diventa size-owner (promote); perdendolo
     // torna ignore-size (demote). Cosi' N deck/tile sulla stessa sessione NON si
     // contendono la geometria: comanda solo chi ha il focus (§5b size policy).
-    else if (msg.type === 'focus') { if (msg.on) pty.promote(); else pty.demote(); }
-    else if (msg.type === 'input') pty.write(typeof msg.data === 'string' ? msg.data : '');
-    else if (msg.type === 'key') pty.write(typeof msg.seq === 'string' ? msg.seq.slice(0, 64) : '');
+    else if (msg.type === 'focus') { if (msg.on) record.pty.promote(); else record.pty.demote(); }
+    else if (msg.type === 'input' && !record.readonly) record.pty.write(typeof msg.data === 'string' ? msg.data : '');
+    else if (msg.type === 'key' && !record.readonly) record.pty.write(typeof msg.seq === 'string' ? msg.seq.slice(0, 64) : '');
     else if (msg.type === 'action') runAction(session, msg.name); // nav window/pane server-side
   }
 
   ws.on('message', onMessage);
-  ws.on('close', () => { clearAttachTimer(); if (pty) pty.kill(); pty = null; });
-  ws.on('error', () => { clearAttachTimer(); if (pty) pty.kill(); pty = null; });
+  ws.on('close', () => { clearAttachTimer(); detach(); });
+  ws.on('error', () => { clearAttachTimer(); detach(); });
 }
-module.exports = { bindWs, clamp };
+module.exports = { bindWs, clamp, createPtyGraceStore, PTY_GRACE_MS };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmmbuto/nexuscrew",
-  "version": "0.9.13",
+  "version": "0.9.15",
   "description": "Faithful browser tmux client — attach to live sessions over a real PTY, localhost-only, mobile-easy",
   "main": "lib/server.js",
   "bin": {