|
| 1 | +/** |
| 2 | + * Regression tests for the backpressure-pause / socket-drop deadlock. |
| 3 | + * |
| 4 | + * The PTY read stream is paused when an attached WebSocket falls behind |
| 5 | + * (bufferedAmount >= high watermark). If that socket then dies *while paused* |
| 6 | + * — e.g. a vite ws-proxy ECONNRESET — the session must resume the PTY, or the |
| 7 | + * child blocks forever on its next stdout write ("running along and then |
| 8 | + * freezes"). These tests pin the resume on both the detach (socket dropped) |
| 9 | + * and the attach-kick (a new client replaces the stalled one) paths. |
| 10 | + * |
| 11 | + * node-pty is mocked so we can drive onData / pause / resume deterministically |
| 12 | + * without spawning a real child. |
| 13 | + */ |
| 14 | + |
| 15 | +import { EventEmitter } from 'node:events'; |
| 16 | +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; |
| 17 | +import * as pty from 'node-pty'; |
| 18 | + |
| 19 | +import { PersistentSession, type PersistentSessionOptions } from './persistent-session.js'; |
| 20 | +import type { Logger } from './logger.js'; |
| 21 | + |
| 22 | +vi.mock('node-pty', () => ({ spawn: vi.fn() })); |
| 23 | + |
| 24 | +const mockSpawn = vi.mocked(pty.spawn); |
| 25 | + |
| 26 | +/** Minimal IPty stand-in that lets the test inject PTY output and observe |
| 27 | + * pause/resume calls. */ |
| 28 | +function makeFakeTerm() { |
| 29 | + let dataCb: ((d: unknown) => void) | undefined; |
| 30 | + return { |
| 31 | + pid: 4321, |
| 32 | + pause: vi.fn(), |
| 33 | + resume: vi.fn(), |
| 34 | + resize: vi.fn(), |
| 35 | + kill: vi.fn(), |
| 36 | + write: vi.fn(), |
| 37 | + clear: vi.fn(), |
| 38 | + onData: (cb: (d: unknown) => void) => { |
| 39 | + dataCb = cb; |
| 40 | + return { dispose: () => {} }; |
| 41 | + }, |
| 42 | + onExit: () => ({ dispose: () => {} }), |
| 43 | + /** test helper — push bytes through the captured onData handler */ |
| 44 | + emitData: (d: Buffer) => dataCb?.(d), |
| 45 | + }; |
| 46 | +} |
| 47 | + |
| 48 | +/** ws.WebSocket stand-in: EventEmitter (for on/off) + send/close + the two |
| 49 | + * fields the backpressure logic reads. */ |
| 50 | +class FakeWs extends EventEmitter { |
| 51 | + readonly OPEN = 1; |
| 52 | + readyState = 1; |
| 53 | + bufferedAmount = 0; |
| 54 | + send = vi.fn((data: unknown, optsOrCb?: unknown, cb?: unknown) => { |
| 55 | + const callback = typeof optsOrCb === 'function' ? optsOrCb : cb; |
| 56 | + if (typeof callback === 'function') callback(undefined); |
| 57 | + }); |
| 58 | + close = vi.fn(); |
| 59 | +} |
| 60 | + |
| 61 | +const silentLogger: Logger = { |
| 62 | + debug: () => {}, |
| 63 | + info: () => {}, |
| 64 | + warn: () => {}, |
| 65 | + error: () => {}, |
| 66 | + event: () => {}, |
| 67 | + child: () => silentLogger, |
| 68 | +}; |
| 69 | + |
| 70 | +function makeOptions(over: Partial<PersistentSessionOptions> = {}): PersistentSessionOptions { |
| 71 | + return { |
| 72 | + wsId: 'ws-1', |
| 73 | + recordId: 'rec-1', |
| 74 | + name: 'c1', |
| 75 | + command: ['claude'], |
| 76 | + cwd: '/tmp', |
| 77 | + env: {}, |
| 78 | + initialCols: 80, |
| 79 | + initialRows: 24, |
| 80 | + logger: silentLogger, |
| 81 | + replayBufferBytes: 1 << 20, |
| 82 | + highWatermarkBytes: 1024, // small so one write trips backpressure |
| 83 | + lowWatermarkBytes: 256, |
| 84 | + onDisposed: () => {}, |
| 85 | + ...over, |
| 86 | + }; |
| 87 | +} |
| 88 | + |
| 89 | +describe('PersistentSession backpressure / socket-drop deadlock', () => { |
| 90 | + let term: ReturnType<typeof makeFakeTerm>; |
| 91 | + |
| 92 | + beforeEach(() => { |
| 93 | + term = makeFakeTerm(); |
| 94 | + mockSpawn.mockReturnValue(term as unknown as pty.IPty); |
| 95 | + }); |
| 96 | + |
| 97 | + afterEach(() => { |
| 98 | + vi.clearAllMocks(); |
| 99 | + }); |
| 100 | + |
| 101 | + it('resumes the PTY when a backpressure-paused socket drops (detach)', () => { |
| 102 | + const session = new PersistentSession(makeOptions()); |
| 103 | + const ws = new FakeWs(); |
| 104 | + session.attach(ws as never, 80, 24, undefined); |
| 105 | + |
| 106 | + // Socket is full: the next chunk of PTY output trips the high watermark |
| 107 | + // and pauses the read stream. |
| 108 | + ws.bufferedAmount = 2048; |
| 109 | + term.emitData(Buffer.from('a lot of output')); |
| 110 | + expect(term.pause).toHaveBeenCalledTimes(1); |
| 111 | + expect(term.resume).not.toHaveBeenCalled(); |
| 112 | + |
| 113 | + // The socket dies mid-backpressure (ECONNRESET) → 'close' → detach(). |
| 114 | + ws.emit('close'); |
| 115 | + |
| 116 | + // Without the fix the PTY stays paused forever and the agent freezes. |
| 117 | + expect(term.resume).toHaveBeenCalledTimes(1); |
| 118 | + |
| 119 | + session.dispose('test'); |
| 120 | + }); |
| 121 | + |
| 122 | + it('resumes a stalled PTY when a new client kicks the old one (attach)', () => { |
| 123 | + const session = new PersistentSession(makeOptions()); |
| 124 | + const ws1 = new FakeWs(); |
| 125 | + session.attach(ws1 as never, 80, 24, undefined); |
| 126 | + |
| 127 | + ws1.bufferedAmount = 2048; |
| 128 | + term.emitData(Buffer.from('a lot of output')); |
| 129 | + expect(term.pause).toHaveBeenCalledTimes(1); |
| 130 | + |
| 131 | + // A fresh tab attaches and kicks ws1. The new attach must un-stick the PTY |
| 132 | + // even though the kick path (not detach) cleared the old socket. |
| 133 | + const ws2 = new FakeWs(); |
| 134 | + session.attach(ws2 as never, 80, 24, undefined); |
| 135 | + |
| 136 | + expect(term.resume).toHaveBeenCalledTimes(1); |
| 137 | + |
| 138 | + session.dispose('test'); |
| 139 | + }); |
| 140 | + |
| 141 | + it('does not resume a PTY that was never paused', () => { |
| 142 | + const session = new PersistentSession(makeOptions()); |
| 143 | + const ws = new FakeWs(); |
| 144 | + session.attach(ws as never, 80, 24, undefined); |
| 145 | + |
| 146 | + // Output flows while the socket drains fine — no pause, no resume churn. |
| 147 | + term.emitData(Buffer.from('small')); |
| 148 | + ws.emit('close'); |
| 149 | + |
| 150 | + expect(term.pause).not.toHaveBeenCalled(); |
| 151 | + expect(term.resume).not.toHaveBeenCalled(); |
| 152 | + |
| 153 | + session.dispose('test'); |
| 154 | + }); |
| 155 | +}); |
0 commit comments