/** * T13 tests — session/manager.ts (session table lifecycle). * * ARCHITECTURE §3.5 + the cross-validated fixes: * - M3: reapIdle uses now - max(detachedAt, lastOutputAt) > idleTtlMs * (not just detachedAt, so active sessions with recent output are not reaped). * - M4: createSession throwing propagates out of handleAttach (not swallowed). * - L1: attach hitting an already-exited session → replay buffer + resend exit + remove. * - L2: the onExit callback injected into createSession removes the session from the table. * * node-pty is mocked so spawn returns a MockIPty — no real PTY/shell is started. */ import { describe, it, expect, beforeEach, vi } from 'vitest'; import type { Config, Dims, Session, WebSocketLike } from '../src/types.js'; import { WS_OPEN } from '../src/types.js'; import { createMockPty, type MockIPty } from './helpers/mock-pty.js'; // ── node-pty mock ─────────────────────────────────────────────────────────── // All createSession calls ultimately call spawn; we intercept at the node-pty // boundary so the session module works exactly as in production, but no real // shell is ever spawned. let nextPty: MockIPty = createMockPty(); let spawnShouldThrow: Error | null = null; vi.mock('node-pty', () => ({ spawn: (_file: string, _args: string[], _options: unknown) => { if (spawnShouldThrow) throw spawnShouldThrow; return nextPty; }, })); // Import AFTER vi.mock so the module under test binds to the mocked spawn. const { createSessionManager } = await import('../src/session/manager.js'); // ── Helpers ────────────────────────────────────────────────────────────────── const CFG: Config = { port: 3000, bindHost: '0.0.0.0', shellPath: '/bin/zsh', homeDir: '/home/tester', idleTtlMs: 10_000, // 10 s for easy arithmetic in tests scrollbackBytes: 2 * 1024 * 1024, maxPayloadBytes: 1024 * 1024, wsPath: '/term', useTmux: false, allowedOrigins: [], }; const DIMS: Dims = { cols: 80, rows: 24 }; interface MockWs extends WebSocketLike { readyState: number; sent: string[]; closed: boolean; } function createMockWs(readyState: number = WS_OPEN): MockWs { const sent: string[] = []; return { readyState, sent, closed: false, send(data: string) { sent.push(data); }, close() { this.closed = true; this.readyState = 3; // CLOSED }, }; } function parseSent(ws: MockWs) { return ws.sent.map((s) => JSON.parse(s)); } beforeEach(() => { nextPty = createMockPty(); spawnShouldThrow = null; }); // ── handleAttach: null sessionId → new session ──────────────────────────────── describe('handleAttach — null sessionId', () => { it('creates a new session and returns it', () => { const mgr = createSessionManager(CFG); const ws = createMockWs(); const session = mgr.handleAttach(ws, null, DIMS, 1_000); expect(session).toBeDefined(); expect(session.meta.id).toBeTruthy(); expect(session.clients.has(ws)).toBe(true); }); it('stores the session so get() returns it', () => { const mgr = createSessionManager(CFG); const ws = createMockWs(); const session = mgr.handleAttach(ws, null, DIMS, 1_000); expect(mgr.get(session.meta.id)).toBe(session); }); it('propagates spawn failure without swallowing it (M4)', () => { spawnShouldThrow = new Error('spawn failed: /no/such/shell ENOENT'); const mgr = createSessionManager(CFG); const ws = createMockWs(); expect(() => mgr.handleAttach(ws, null, DIMS, 1_000)).toThrow(/spawn failed/); }); }); // ── handleAttach: hit live session ──────────────────────────────────────────── describe('handleAttach — hit live session', () => { it('JOINS the new ws and returns the same session (multi-device share)', () => { const mgr = createSessionManager(CFG); const ws1 = createMockWs(); const session = mgr.handleAttach(ws1, null, DIMS, 1_000); const id = session.meta.id; const ws2 = createMockWs(); const session2 = mgr.handleAttach(ws2, id, DIMS, 2_000); expect(session2).toBe(session); // Both clients share the session now. expect(session.clients.has(ws1)).toBe(true); expect(session.clients.has(ws2)).toBe(true); }); it('does NOT kick the previously attached ws (v0.4 sharing)', () => { const mgr = createSessionManager(CFG); const ws1 = createMockWs(); const session = mgr.handleAttach(ws1, null, DIMS, 1_000); const id = session.meta.id; const ws2 = createMockWs(); mgr.handleAttach(ws2, id, DIMS, 2_000); // The old ws must stay open — devices mirror the session. expect(ws1.closed).toBe(false); expect(session.clients.size).toBe(2); }); it('broadcasts live output to ALL joined clients', () => { const mgr = createSessionManager(CFG); const ws1 = createMockWs(); const session = mgr.handleAttach(ws1, null, DIMS, 1_000); const ws2 = createMockWs(); mgr.handleAttach(ws2, session.meta.id, DIMS, 2_000); ws1.sent.length = 0; ws2.sent.length = 0; (session.pty as MockIPty).emitData('to everyone'); expect(parseSent(ws1).some((m) => m.type === 'output' && m.data === 'to everyone')).toBe(true); expect(parseSent(ws2).some((m) => m.type === 'output' && m.data === 'to everyone')).toBe(true); }); it('replays the buffer to the new ws', () => { const mgr = createSessionManager(CFG); const ws1 = createMockWs(); const session = mgr.handleAttach(ws1, null, DIMS, 1_000); const id = session.meta.id; // Produce some output while ws1 is attached. (session.pty as MockIPty).emitData('hello world'); const ws2 = createMockWs(); mgr.handleAttach(ws2, id, DIMS, 2_000); const msgs = parseSent(ws2); const outputMsgs = msgs.filter((m) => m.type === 'output'); expect(outputMsgs.some((m: { data: string }) => m.data.includes('hello world'))).toBe(true); }); }); // ── handleAttach: hit already-exited session (L1) ───────────────────────────── describe('handleAttach — hit already-exited session (L1)', () => { it('sends the buffer snapshot to the new ws', () => { const mgr = createSessionManager(CFG); const ws1 = createMockWs(); const session = mgr.handleAttach(ws1, null, DIMS, 1_000); const id = session.meta.id; // Build some output, then detach ws1, then simulate PTY exit. (session.pty as MockIPty).emitData('last output before exit'); mgr.handleAttach(createMockWs(), id, DIMS, 2_000); // re-attach so we can detach // Force detach by patching directly (simulates WS close event). session.clients.clear(); session.detachedAt = 3_000; // Now PTY exits while detached — session preserved (L1). (session.pty as MockIPty).emitExit(0); // session.exitedAt is set, session still in table because onExit in detach // scenario keeps session (manager's onExit callback removes from table only if // invoked — but per L2, after exit while attached ws exists the callback removes, // while L1 says detach-then-exit: we must keep for replay). // Actually per ARCHITECTURE: the injected onExit IS called by session.ts after exit. // But the L1 scenario means: exitedAt!=null, session is in table until re-attach. // We re-insert it manually to simulate the correct state from ARCHITECTURE §4.4: // "session is preserved (buffer + exitedAt)" waiting for re-attach. // The key thing to test is that when a NEW ws comes with this session's id, // the manager replays the buffer + sends exit + removes from table. // For this test: we need the session to still be in the map with exitedAt set. // The manager's injected onExit should NOT remove from table in this case — // But wait: per ARCHITECTURE §3.5 L2: "PTY 退出: injected onExit → 从表删除" // And L1: "detach后exit → 保留buffer+exitedAt, 等用户回来attach" // These seem contradictory. Let me re-read: // // ARCHITECTURE §3.5 constraint: "PTY 退出: createSession 内部 onExit → 置 exitedAt → // 有 ws 则发 exit → 调 manager 注入的回调从表移除 (L2)" // ARCHITECTURE §3.5 L1: "detach 后才退出(无 ws 可通知, L1): 不立即丢弃会话, 保留 // buffer + exitedAt, 等用户带旧 id 回来 attach 时回放 + 补发 exit" // // Resolution: L2 says "从表移除" — but L1 says "不立即丢弃". So L2 applies when // attachedWs is NOT null (ws is attached), and L1 applies when detached. // The manager's injected onExit callback should: // - Only remove from table if attachedWs != null at exit time (ws was attached) // - Keep in table if detached at exit time (for L1 replay on reconnect) // // But PLAN.md T13 Steps says: "注入给 createSession 的 onExit: 从会话表删除该会话 (L2)" // And the task prompt says: "L2: onExit 从会话表删除" // And also: "命中已退出会话(exitedAt!=null) → 回放+补发exit后从表移除(L1)" // // So the behavior is: // - When PTY exits with ws attached: onExit removes from table immediately (L2). // - When PTY exits while detached (L1): onExit does NOT remove; session stays. // The session is removed when the next attach hits it and sees exitedAt!=null. // // This means the manager's onExit callback must check attachedWs: if null, keep. // If ws attached, remove. // // Actually re-reading ARCHITECTURE §3.5 more carefully: // The constraint says: "PTY 退出: session 内部 onExit → 置 exitedAt → 有 ws 则发 exit // → 调 manager 注入的回调从表移除 (L2: session 不持有 manager, 退出事件靠注入回调跨层冒泡)" // // This says "调 manager 注入的回调从表移除" — it calls the callback and removes. // But L1 says "不立即丢弃". These are the same callback situation. // // Looking at PLAN T13 instruction: "注入给 createSession 的 onExit: 从会话表删除该会话 (L2)" // And the task prompt: "命中已退出 → 回放+补发exit+移除 → 从表移除(L1)" // // The reconciliation: L2's callback ALWAYS removes the session from the table when // called. L1 means: when the session exits while detached, the session stays in the // table BECAUSE the onExit in the detach case should NOT remove it immediately. // // Wait, but the task prompt says "注入给 createSession 的 onExit: 从会话表删除该会话 (L2)" // unconditionally. And L1 says "保留 buffer + exitedAt". // // The only way to reconcile: the onExit callback should NOT remove when detached. // The callback should check session.attachedWs (which is null when detached): // if (session.attachedWs !== null) → remove from table (session was live) // if (session.attachedWs === null) → keep in table (for L1 replay) // // This matches ARCHITECTURE §4.4: "[在 detach 状态下退出] pty.onExit → 置 exitedAt/exitCode // → attachedWs 为 null, exit 暂不投递 → 会话保留(buffer + exitedAt)" // And the session.ts onExit flow: sets exitedAt, sends exit if ws, calls manager onExit. // // So the manager's onExit MUST only remove when ws was attached. When detached, // it should keep the session for L1 replay. // // CONCLUSION: The injected onExit callback in the manager checks session.attachedWs: // - non-null → ws existed when exit fired → remove from table (L2) // - null → detached-then-exit → keep in table for L1 replay // At this point, session.exitedAt should be set, and session should still be in table. expect(session.exitedAt).not.toBeNull(); // Now a new ws comes back with the same session id: const ws2 = createMockWs(); // Need to re-add session to map manually IF the onExit removed it. // Let's just test the flow by checking what actually happens: const result = mgr.handleAttach(ws2, id, DIMS, 5_000); // The manager should have replayed the buffer to ws2. const msgs = parseSent(ws2); const outputMsgs = msgs.filter((m: { type: string }) => m.type === 'output'); expect(outputMsgs.some((m: { data: string }) => m.data.includes('last output before exit'))).toBe(true); }); it('sends exit message to the new ws after replay (L1)', () => { const mgr = createSessionManager(CFG); const ws1 = createMockWs(); const session = mgr.handleAttach(ws1, null, DIMS, 1_000); const id = session.meta.id; // Detach by simulating WS close. session.clients.clear(); session.detachedAt = 2_000; // PTY exits while detached. (session.pty as MockIPty).emitExit(42); expect(session.exitedAt).not.toBeNull(); expect(session.exitCode).toBe(42); // New ws comes back. const ws2 = createMockWs(); mgr.handleAttach(ws2, id, DIMS, 5_000); const msgs = parseSent(ws2); const exitMsgs = msgs.filter((m: { type: string }) => m.type === 'exit'); expect(exitMsgs).toHaveLength(1); expect(exitMsgs[0]).toMatchObject({ type: 'exit', code: 42 }); }); it('removes the exited session from the table after replay (L1)', () => { const mgr = createSessionManager(CFG); const ws1 = createMockWs(); const session = mgr.handleAttach(ws1, null, DIMS, 1_000); const id = session.meta.id; // Detach and exit. session.clients.clear(); session.detachedAt = 2_000; (session.pty as MockIPty).emitExit(0); // Reconnect triggers L1 replay + removal. const ws2 = createMockWs(); mgr.handleAttach(ws2, id, DIMS, 5_000); // Session must be gone from the table now. expect(mgr.get(id)).toBeUndefined(); }); }); // ── handleAttach: session not found → new session ───────────────────────────── describe('handleAttach — session not found', () => { it('creates a new session when the given id does not exist', () => { const mgr = createSessionManager(CFG); const ws = createMockWs(); const unknownId = '00000000-0000-4000-8000-000000000000'; const session = mgr.handleAttach(ws, unknownId, DIMS, 1_000); expect(session).toBeDefined(); // The returned session has a NEW id (not the bogus one). expect(session.meta.id).not.toBe(unknownId); expect(session.clients.has(ws)).toBe(true); }); it('the newly created session is stored in the table', () => { const mgr = createSessionManager(CFG); const ws = createMockWs(); const unknownId = '00000000-0000-4000-8000-000000000001'; const session = mgr.handleAttach(ws, unknownId, DIMS, 1_000); expect(mgr.get(session.meta.id)).toBe(session); // Old unknown id is NOT stored. expect(mgr.get(unknownId)).toBeUndefined(); }); }); // ── get ─────────────────────────────────────────────────────────────────────── describe('get', () => { it('returns undefined for unknown ids', () => { const mgr = createSessionManager(CFG); expect(mgr.get('00000000-0000-4000-8000-000000000002')).toBeUndefined(); }); it('returns the session for a known id', () => { const mgr = createSessionManager(CFG); const ws = createMockWs(); const session = mgr.handleAttach(ws, null, DIMS, 1_000); expect(mgr.get(session.meta.id)).toBe(session); }); }); // ── reapIdle (M3) ───────────────────────────────────────────────────────────── describe('reapIdle (M3)', () => { it('does not reap a session that is still attached', () => { const mgr = createSessionManager(CFG); const ws = createMockWs(); const session = mgr.handleAttach(ws, null, DIMS, 1_000); // Not detached, so detachedAt = null → not eligible. const reaped = mgr.reapIdle(1_000 + CFG.idleTtlMs + 1); expect(reaped).toBe(0); expect(mgr.get(session.meta.id)).toBeDefined(); }); it('does not reap a detached session that received output recently (M3)', () => { const mgr = createSessionManager(CFG); const ws = createMockWs(); const session = mgr.handleAttach(ws, null, DIMS, 1_000); const id = session.meta.id; // Detach at t=2000. session.clients.clear(); session.detachedAt = 2_000; // Output arrives at t=5000 (AFTER detach) — refresh lastOutputAt. (session.pty as MockIPty).emitData('fresh output'); // Force the lastOutputAt to a specific value we can assert against. session.lastOutputAt = 5_000; // Now reap at t = 5000 + idleTtl - 1 → not yet expired relative to lastOutputAt. const reaped = mgr.reapIdle(5_000 + CFG.idleTtlMs - 1); expect(reaped).toBe(0); expect(mgr.get(id)).toBeDefined(); expect((session.pty as MockIPty).killed).toBe(false); }); it('reaps a detached session whose max(detachedAt, lastOutputAt) + idleTtl has passed (M3)', () => { const mgr = createSessionManager(CFG); const ws = createMockWs(); const session = mgr.handleAttach(ws, null, DIMS, 1_000); const id = session.meta.id; // Detach at t=2000; no output after detach. session.clients.clear(); session.detachedAt = 2_000; session.lastOutputAt = 1_500; // before detach → max = 2000 // Reap at t = 2000 + idleTtl + 1 → expired. const reaped = mgr.reapIdle(2_000 + CFG.idleTtlMs + 1); expect(reaped).toBe(1); expect(mgr.get(id)).toBeUndefined(); expect((session.pty as MockIPty).killed).toBe(true); }); it('reaps multiple idle sessions and returns the count', () => { const mgr = createSessionManager(CFG); // Session A — will be reaped. nextPty = createMockPty(); const wsA = createMockWs(); const sessionA = mgr.handleAttach(wsA, null, DIMS, 1_000); sessionA.clients.clear(); sessionA.detachedAt = 1_000; sessionA.lastOutputAt = 1_000; // Session B — will be reaped. nextPty = createMockPty(); const wsB = createMockWs(); const sessionB = mgr.handleAttach(wsB, null, DIMS, 1_000); sessionB.clients.clear(); sessionB.detachedAt = 1_000; sessionB.lastOutputAt = 1_000; const reaped = mgr.reapIdle(1_000 + CFG.idleTtlMs + 1); expect(reaped).toBe(2); expect(mgr.get(sessionA.meta.id)).toBeUndefined(); expect(mgr.get(sessionB.meta.id)).toBeUndefined(); }); it('does not reap if detachedAt is null (still attached / never detached)', () => { const mgr = createSessionManager(CFG); const ws = createMockWs(); const session = mgr.handleAttach(ws, null, DIMS, 1_000); // detachedAt is null — session is still live. const reaped = mgr.reapIdle(99_999_999); expect(reaped).toBe(0); expect(mgr.get(session.meta.id)).toBeDefined(); }); }); // ── list (v0.4 multi-device discovery) ──────────────────────────────────────── describe('list', () => { it('returns live sessions with client counts, newest first', () => { const mgr = createSessionManager(CFG); nextPty = createMockPty(); const a = mgr.handleAttach(createMockWs(), null, DIMS, 1_000); nextPty = createMockPty(); const b = mgr.handleAttach(createMockWs(), null, DIMS, 2_000); // a second device joins session b → clientCount 2 mgr.handleAttach(createMockWs(), b.meta.id, DIMS, 2_500); const list = mgr.list(); expect(list.map((s) => s.id)).toEqual([b.meta.id, a.meta.id]); // newest first expect(list.find((s) => s.id === b.meta.id)?.clientCount).toBe(2); expect(list.find((s) => s.id === a.meta.id)?.clientCount).toBe(1); expect(list.every((s) => s.exited === false)).toBe(true); }); it('returns an empty array when there are no sessions', () => { const mgr = createSessionManager(CFG); expect(mgr.list()).toEqual([]); }); }); // ── shutdown ────────────────────────────────────────────────────────────────── describe('shutdown', () => { it('kills all sessions and clears the table', () => { const mgr = createSessionManager(CFG); nextPty = createMockPty(); const ws1 = createMockWs(); const s1 = mgr.handleAttach(ws1, null, DIMS, 1_000); nextPty = createMockPty(); const ws2 = createMockWs(); const s2 = mgr.handleAttach(ws2, null, DIMS, 1_000); mgr.shutdown(); expect((s1.pty as MockIPty).killed).toBe(true); expect((s2.pty as MockIPty).killed).toBe(true); // Table is cleared. expect(mgr.get(s1.meta.id)).toBeUndefined(); expect(mgr.get(s2.meta.id)).toBeUndefined(); }); }); // ── L2: injected onExit removes session when ws is attached at exit time ─────── describe('onExit removes session from table when ws attached at exit time (L2)', () => { it('session is removed from the table when PTY exits while ws is attached', () => { const mgr = createSessionManager(CFG); const ws = createMockWs(); const session = mgr.handleAttach(ws, null, DIMS, 1_000); const id = session.meta.id; // PTY exits while ws is still attached. (session.pty as MockIPty).emitExit(0); // The manager's onExit should have removed the session. expect(mgr.get(id)).toBeUndefined(); }); it('session is NOT removed from table when PTY exits while detached (kept for L1 replay)', () => { const mgr = createSessionManager(CFG); const ws = createMockWs(); const session = mgr.handleAttach(ws, null, DIMS, 1_000); const id = session.meta.id; // Detach first. session.clients.clear(); session.detachedAt = 2_000; // Then PTY exits. (session.pty as MockIPty).emitExit(0); // Session must stay in table for L1 replay. expect(mgr.get(id)).toBeDefined(); expect(session.exitedAt).not.toBeNull(); }); });