web-terminal/test/manager.test.ts

/**
 * 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.attachedWs).toBe(ws);
  });

  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('attaches the new ws and returns the same session', () => {
    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);
    expect(session.attachedWs).toBe(ws2);
  });

  it('kicks (closes) the previously attached ws', () => {
    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 should have been closed by the manager.
    expect(ws1.closed).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.attachedWs = null;
    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.attachedWs = null;
    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.attachedWs = null;
    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.attachedWs).toBe(ws);
  });

  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.attachedWs = null;
    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.attachedWs = null;
    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.attachedWs = null;
    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.attachedWs = null;
    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();
  });
});

// ── 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.attachedWs = null;
    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();
  });
});