feat(v0.4): multi-device session sharing (backend)
Relax the one-WS-per-session invariant (#5) so multiple devices mirror the same live terminal (everyone sees output, anyone can type — tmux-style). - types.ts: Session.attachedWs → clients Set + clientDims Map; add cwd; SessionManager.list() + LiveSessionInfo - session.ts: broadcast() output/exit to all clients; attachWs JOINS (no kick, takes dims); detachWs removes one client, stamps detachedAt only when the last leaves; setClientDims resizes PTY to the MIN cols/rows across clients - manager.ts: join instead of kick; broadcast status; onExit drops only when a client was attached; list() for discovery - server.ts: GET /live-sessions; resize → per-client setClientDims; close → detach one client; permission gate uses clients.size - tests: rewrote session/manager tests for multi-client (join/broadcast/min-dims/ last-detach) + list(); 222 pass, tsc clean
This commit is contained in:
Yaojia Wang
@@ -1,15 +1,16 @@
|
||||
/**
|
||||
* T12 tests — session/session.ts (single-session lifecycle).
|
||||
* T12 tests — session/session.ts (PTY lifecycle + multi-client sharing).
|
||||
*
|
||||
* ARCHITECTURE §3.4 / §4.4 + the cross-validated fixes:
|
||||
* - M4: spawn failure THROWS, never swallowed.
|
||||
* - M5: every ws.send is guarded by `ws.readyState === WS_OPEN`.
|
||||
* - L1: detach-then-exit keeps the session (exit not delivered when attachedWs is null).
|
||||
* - L4: writeInput/resize are no-ops once the PTY has exited.
|
||||
* - L1: detach-then-exit keeps the session (exit not delivered when no client attached).
|
||||
* - L4: writeInput/setClientDims are no-ops once the PTY has exited.
|
||||
* - v0.4: a session may hold MANY clients (multi-device mirror). Output/exit are
|
||||
* broadcast to all; the PTY size is the MIN cols/rows across clients.
|
||||
*
|
||||
* node-pty is mocked (`vi.mock`) so `spawn` returns a MockIPty — the sandbox blocks
|
||||
* real posix_spawn, and the mock lets us drive onData/onExit deterministically and
|
||||
* assert lifecycle without a real shell.
|
||||
* real posix_spawn, and the mock lets us drive onData/onExit deterministically.
|
||||
*/
|
||||
|
||||
import { describe, it, expect, beforeEach, vi } from 'vitest';
|
||||
@@ -19,8 +20,6 @@ import { WS_OPEN } from '../src/types.js';
|
||||
import { createMockPty, type MockIPty } from './helpers/mock-pty.js';
|
||||
|
||||
// ── node-pty mock ───────────────────────────────────────────────────────────
|
||||
// spawn returns whatever `nextPty` points at, and records its call args so we
|
||||
// can assert how createSession invoked it (and force it to throw for M4).
|
||||
let nextPty: MockIPty;
|
||||
let spawnError: Error | null = null;
|
||||
const spawnCalls: Array<{ file: string; args: string[] | string; options: unknown }> = [];
|
||||
@@ -34,7 +33,7 @@ vi.mock('node-pty', () => ({
|
||||
}));
|
||||
|
||||
// Imported AFTER vi.mock so the module under test binds to the mocked spawn.
|
||||
const { createSession, attachWs, detachWs, writeInput, resize, kill } = await import(
|
||||
const { createSession, attachWs, detachWs, writeInput, setClientDims, kill } = await import(
|
||||
'../src/session/session.js'
|
||||
);
|
||||
|
||||
@@ -105,7 +104,7 @@ describe('createSession', () => {
|
||||
expect(s.pty).toBe(nextPty);
|
||||
expect(s.meta.shellPath).toBe(CFG.shellPath);
|
||||
expect(s.meta.createdAt).toBe(1_000);
|
||||
expect(s.attachedWs).toBeNull();
|
||||
expect(s.clients.size).toBe(0);
|
||||
expect(s.exitedAt).toBeNull();
|
||||
expect(s.exitCode).toBeNull();
|
||||
});
|
||||
@@ -118,7 +117,7 @@ describe('createSession', () => {
|
||||
});
|
||||
});
|
||||
|
||||
// ── onData → buffer + forward ──────────────────────────────────────────────────
|
||||
// ── onData → buffer + broadcast ────────────────────────────────────────────────
|
||||
describe('onData', () => {
|
||||
it('appends output to the ring buffer and refreshes lastOutputAt', () => {
|
||||
const s = newSession();
|
||||
@@ -127,15 +126,14 @@ describe('onData', () => {
|
||||
pty.emitData('hello ');
|
||||
pty.emitData('world');
|
||||
|
||||
// buffer snapshot prepends the M2 soft-reset, then the verbatim output.
|
||||
expect(s.buffer.snapshot()).toBe('\x1b[0mhello world');
|
||||
expect(s.lastOutputAt).toBeGreaterThanOrEqual(1_000);
|
||||
});
|
||||
|
||||
it('forwards output to the attached ws as an `output` message', () => {
|
||||
it('broadcasts output to the attached client as an `output` message', () => {
|
||||
const s = newSession();
|
||||
const ws = createMockWs();
|
||||
attachWs(s, ws);
|
||||
attachWs(s, ws, DIMS);
|
||||
ws.sent.length = 0; // drop the replay frame from attach
|
||||
|
||||
(s.pty as MockIPty).emitData('abc');
|
||||
@@ -143,16 +141,31 @@ describe('onData', () => {
|
||||
expect(received(ws)).toEqual([{ type: 'output', data: 'abc' }]);
|
||||
});
|
||||
|
||||
it('still buffers output when no ws is attached (does not throw)', () => {
|
||||
it('broadcasts output to EVERY client sharing the session (multi-device)', () => {
|
||||
const s = newSession();
|
||||
const a = createMockWs();
|
||||
const b = createMockWs();
|
||||
attachWs(s, a, DIMS);
|
||||
attachWs(s, b, DIMS);
|
||||
a.sent.length = 0;
|
||||
b.sent.length = 0;
|
||||
|
||||
(s.pty as MockIPty).emitData('shared');
|
||||
|
||||
expect(received(a)).toEqual([{ type: 'output', data: 'shared' }]);
|
||||
expect(received(b)).toEqual([{ type: 'output', data: 'shared' }]);
|
||||
});
|
||||
|
||||
it('still buffers output when no client is attached (does not throw)', () => {
|
||||
const s = newSession();
|
||||
expect(() => (s.pty as MockIPty).emitData('orphan')).not.toThrow();
|
||||
expect(s.buffer.snapshot()).toContain('orphan');
|
||||
});
|
||||
|
||||
it('does NOT send to a ws whose readyState is not OPEN (M5)', () => {
|
||||
it('does NOT send to a client whose readyState is not OPEN (M5)', () => {
|
||||
const s = newSession();
|
||||
const ws = createMockWs(WS_OPEN);
|
||||
attachWs(s, ws);
|
||||
attachWs(s, ws, DIMS);
|
||||
ws.sent.length = 0;
|
||||
|
||||
ws.readyState = 3; // CLOSED
|
||||
@@ -162,60 +175,97 @@ describe('onData', () => {
|
||||
});
|
||||
});
|
||||
|
||||
// ── attachWs ──────────────────────────────────────────────────────────────────
|
||||
// ── attachWs (join, no kick) ──────────────────────────────────────────────────
|
||||
describe('attachWs', () => {
|
||||
it('replays the buffer snapshot to the newly attached ws', () => {
|
||||
it('replays the buffer snapshot to the newly attached client', () => {
|
||||
const s = newSession();
|
||||
(s.pty as MockIPty).emitData('prior output');
|
||||
|
||||
const ws = createMockWs();
|
||||
const kicked = attachWs(s, ws);
|
||||
attachWs(s, ws, DIMS);
|
||||
|
||||
expect(kicked).toBeNull();
|
||||
expect(s.attachedWs).toBe(ws);
|
||||
expect(s.clients.has(ws)).toBe(true);
|
||||
expect(received(ws)).toEqual([{ type: 'output', data: '\x1b[0mprior output' }]);
|
||||
});
|
||||
|
||||
it('points attachedWs at the new ws BEFORE returning the kicked old ws (later wins)', () => {
|
||||
it('a second attach JOINS (does not kick) — both clients stay connected', () => {
|
||||
const s = newSession();
|
||||
const oldWs = createMockWs();
|
||||
attachWs(s, oldWs);
|
||||
const a = createMockWs();
|
||||
attachWs(s, a, DIMS);
|
||||
|
||||
const newWs = createMockWs();
|
||||
const kicked = attachWs(s, newWs);
|
||||
const b = createMockWs();
|
||||
attachWs(s, b, DIMS);
|
||||
|
||||
// pointer is swapped first; caller is responsible for closing the kicked ws.
|
||||
expect(s.attachedWs).toBe(newWs);
|
||||
expect(kicked).toBe(oldWs);
|
||||
expect(oldWs.closed).toBe(false); // attachWs must NOT close it itself
|
||||
// Both present; the first was NOT closed.
|
||||
expect(s.clients.has(a)).toBe(true);
|
||||
expect(s.clients.has(b)).toBe(true);
|
||||
expect(a.closed).toBe(false);
|
||||
|
||||
// forwarding now only ever reaches the new ws.
|
||||
newWs.sent.length = 0;
|
||||
(s.pty as MockIPty).emitData('after kick');
|
||||
expect(received(newWs)).toEqual([{ type: 'output', data: 'after kick' }]);
|
||||
expect(oldWs.sent.some((f) => f.includes('after kick'))).toBe(false);
|
||||
// Only the joining client got the replay; live output reaches both.
|
||||
a.sent.length = 0;
|
||||
b.sent.length = 0;
|
||||
(s.pty as MockIPty).emitData('live');
|
||||
expect(received(a)).toEqual([{ type: 'output', data: 'live' }]);
|
||||
expect(received(b)).toEqual([{ type: 'output', data: 'live' }]);
|
||||
});
|
||||
|
||||
it('resizes the PTY to the MIN dims across all clients (tmux-style)', () => {
|
||||
const s = newSession(); // spawn dims 80x24
|
||||
const wide = createMockWs();
|
||||
const narrow = createMockWs();
|
||||
|
||||
attachWs(s, wide, { cols: 200, rows: 50 });
|
||||
// one client at 200x50 → PTY grows to 200x50
|
||||
expect(s.pty.cols).toBe(200);
|
||||
expect(s.pty.rows).toBe(50);
|
||||
|
||||
attachWs(s, narrow, { cols: 90, rows: 30 });
|
||||
// min(200,90)=90, min(50,30)=30
|
||||
expect(s.pty.cols).toBe(90);
|
||||
expect(s.pty.rows).toBe(30);
|
||||
});
|
||||
});
|
||||
|
||||
// ── detachWs ──────────────────────────────────────────────────────────────────
|
||||
// ── detachWs (remove one client) ──────────────────────────────────────────────
|
||||
describe('detachWs', () => {
|
||||
it('clears attachedWs and stamps detachedAt but NEVER kills the PTY', () => {
|
||||
it('removes the client and stamps detachedAt only when the LAST one leaves', () => {
|
||||
const s = newSession();
|
||||
const ws = createMockWs();
|
||||
attachWs(s, ws);
|
||||
const a = createMockWs();
|
||||
const b = createMockWs();
|
||||
attachWs(s, a, DIMS);
|
||||
attachWs(s, b, DIMS);
|
||||
|
||||
detachWs(s, 5_000);
|
||||
detachWs(s, a, 5_000);
|
||||
// one client remains → still "attached", no detach stamp
|
||||
expect(s.clients.has(a)).toBe(false);
|
||||
expect(s.clients.has(b)).toBe(true);
|
||||
expect(s.detachedAt).toBeNull();
|
||||
|
||||
expect(s.attachedWs).toBeNull();
|
||||
expect(s.detachedAt).toBe(5_000);
|
||||
detachWs(s, b, 6_000);
|
||||
// last client gone → detached
|
||||
expect(s.clients.size).toBe(0);
|
||||
expect(s.detachedAt).toBe(6_000);
|
||||
expect((s.pty as MockIPty).killed).toBe(false);
|
||||
});
|
||||
|
||||
it('keeps the PTY alive after detach: further onData still fills the buffer', () => {
|
||||
it('lets the PTY grow back when a small client leaves', () => {
|
||||
const s = newSession();
|
||||
const wide = createMockWs();
|
||||
const narrow = createMockWs();
|
||||
attachWs(s, wide, { cols: 200, rows: 50 });
|
||||
attachWs(s, narrow, { cols: 90, rows: 30 }); // clamps to 90x30
|
||||
|
||||
detachWs(s, narrow, 5_000);
|
||||
// only the wide client remains → PTY expands back to 200x50
|
||||
expect(s.pty.cols).toBe(200);
|
||||
expect(s.pty.rows).toBe(50);
|
||||
});
|
||||
|
||||
it('keeps the PTY alive after the last detach: further onData still fills the buffer', () => {
|
||||
const s = newSession();
|
||||
const ws = createMockWs();
|
||||
attachWs(s, ws);
|
||||
detachWs(s, 5_000);
|
||||
attachWs(s, ws, DIMS);
|
||||
detachWs(s, ws, 5_000);
|
||||
|
||||
(s.pty as MockIPty).emitData('background work');
|
||||
|
||||
@@ -226,48 +276,50 @@ describe('detachWs', () => {
|
||||
|
||||
// ── onExit ────────────────────────────────────────────────────────────────────
|
||||
describe('onExit', () => {
|
||||
it('sets exitedAt/exitCode, sends `exit` to the attached ws, and calls injected onExit', () => {
|
||||
it('sets exitedAt/exitCode, broadcasts `exit` to all clients, and calls injected onExit', () => {
|
||||
const onExit = vi.fn();
|
||||
nextPty = createMockPty();
|
||||
const s = createSession(CFG, DIMS, 1_000, onExit);
|
||||
|
||||
const ws = createMockWs();
|
||||
attachWs(s, ws);
|
||||
ws.sent.length = 0;
|
||||
const a = createMockWs();
|
||||
const b = createMockWs();
|
||||
attachWs(s, a, DIMS);
|
||||
attachWs(s, b, DIMS);
|
||||
a.sent.length = 0;
|
||||
b.sent.length = 0;
|
||||
|
||||
(s.pty as MockIPty).emitExit(0);
|
||||
|
||||
expect(s.exitedAt).not.toBeNull();
|
||||
expect(s.exitCode).toBe(0);
|
||||
expect(received(ws)).toEqual([{ type: 'exit', code: 0 }]);
|
||||
expect(received(a)).toEqual([{ type: 'exit', code: 0 }]);
|
||||
expect(received(b)).toEqual([{ type: 'exit', code: 0 }]);
|
||||
expect(onExit).toHaveBeenCalledWith(s);
|
||||
});
|
||||
|
||||
it('after detach, exit is NOT delivered but the session is preserved (L1)', () => {
|
||||
it('after the last detach, exit is NOT delivered but the session is preserved (L1)', () => {
|
||||
const onExit = vi.fn();
|
||||
nextPty = createMockPty();
|
||||
const s = createSession(CFG, DIMS, 1_000, onExit);
|
||||
|
||||
const ws = createMockWs();
|
||||
attachWs(s, ws);
|
||||
detachWs(s, 5_000);
|
||||
attachWs(s, ws, DIMS);
|
||||
detachWs(s, ws, 5_000);
|
||||
ws.sent.length = 0;
|
||||
|
||||
(s.pty as MockIPty).emitExit(137);
|
||||
|
||||
// exit happened: state recorded, but no ws to notify → nothing delivered.
|
||||
expect(s.exitedAt).not.toBeNull();
|
||||
expect(s.exitCode).toBe(137);
|
||||
expect(ws.sent).toHaveLength(0);
|
||||
// session preserved: buffer intact (caller/manager decides removal via onExit).
|
||||
expect(onExit).toHaveBeenCalledWith(s);
|
||||
});
|
||||
|
||||
it('does not send exit to a ws whose readyState is not OPEN (M5)', () => {
|
||||
it('does not send exit to a client whose readyState is not OPEN (M5)', () => {
|
||||
nextPty = createMockPty();
|
||||
const s = createSession(CFG, DIMS, 1_000, () => {});
|
||||
const ws = createMockWs(WS_OPEN);
|
||||
attachWs(s, ws);
|
||||
attachWs(s, ws, DIMS);
|
||||
ws.sent.length = 0;
|
||||
ws.readyState = 3; // CLOSED
|
||||
|
||||
@@ -277,27 +329,30 @@ describe('onExit', () => {
|
||||
});
|
||||
});
|
||||
|
||||
// ── writeInput / resize after exit (L4) + resize idempotence ──────────────────
|
||||
describe('writeInput / resize', () => {
|
||||
// ── writeInput / setClientDims after exit (L4) + dims idempotence ──────────────
|
||||
describe('writeInput / setClientDims', () => {
|
||||
it('writeInput forwards to pty.write while alive', () => {
|
||||
const s = newSession();
|
||||
writeInput(s, 'ls\r');
|
||||
expect((s.pty as MockIPty).writes).toEqual(['ls\r']);
|
||||
});
|
||||
|
||||
it('resize forwards to pty.resize while alive', () => {
|
||||
it('setClientDims forwards to pty.resize while alive', () => {
|
||||
const s = newSession();
|
||||
resize(s, 100, 40);
|
||||
expect((s.pty as MockIPty).resizes).toEqual([{ cols: 100, rows: 40 }]);
|
||||
const ws = createMockWs();
|
||||
attachWs(s, ws, DIMS);
|
||||
setClientDims(s, ws, 100, 40);
|
||||
expect((s.pty as MockIPty).resizes).toContainEqual({ cols: 100, rows: 40 });
|
||||
});
|
||||
|
||||
it('resize is idempotent: same cols/rows are skipped', () => {
|
||||
it('setClientDims is idempotent: same min cols/rows are skipped', () => {
|
||||
const s = newSession();
|
||||
resize(s, 80, 24); // equal to the spawn dims → no-op
|
||||
const ws = createMockWs();
|
||||
attachWs(s, ws, DIMS); // 80x24, equals spawn dims → no resize yet
|
||||
expect((s.pty as MockIPty).resizes).toHaveLength(0);
|
||||
|
||||
resize(s, 90, 24); // changed → applied
|
||||
resize(s, 90, 24); // unchanged again → skipped
|
||||
setClientDims(s, ws, 90, 24); // changed → applied
|
||||
setClientDims(s, ws, 90, 24); // unchanged again → skipped
|
||||
expect((s.pty as MockIPty).resizes).toEqual([{ cols: 90, rows: 24 }]);
|
||||
});
|
||||
|
||||
@@ -309,11 +364,13 @@ describe('writeInput / resize', () => {
|
||||
expect((s.pty as MockIPty).writes).toHaveLength(0);
|
||||
});
|
||||
|
||||
it('ignores resize once the PTY has exited (L4)', () => {
|
||||
it('ignores setClientDims once the PTY has exited (L4)', () => {
|
||||
const s = newSession();
|
||||
const ws = createMockWs();
|
||||
attachWs(s, ws, DIMS);
|
||||
(s.pty as MockIPty).emitExit(0);
|
||||
|
||||
resize(s, 200, 50);
|
||||
setClientDims(s, ws, 200, 50);
|
||||
expect((s.pty as MockIPty).resizes).toHaveLength(0);
|
||||
});
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user