Skip to content

Commit e9c174d

Browse files
okwasniewskithymikee
authored andcommitted
fix(client): confirm a companion exit before dropping its state
The host refusing SIGTERM was reported as a completed stop, so the profile forgot a live companion and a second one could start beside it. An unreadable identity had the same effect through a different door: on Windows an elevated process answers the command-line query with nothing, and the stop path read that as 'not our companion' and cleared the state. Signals now settle against the host in one place. stopProcessAndConfirmExit takes the identity the caller recorded - the start time and a command matcher - and reports how the process ended: only a released pid, a zombie, or an identity the host contradicts proves the exit; a refusal is retained with its errno, and a pid nobody can describe is retained as identity-unverified without being signalled at all. The companion state is dropped only on 'stopped', and the failure names the pid, the reason, and the state file so a retry stops the same process.
1 parent a95d2d5 commit e9c174d

7 files changed

Lines changed: 731 additions & 188 deletions

File tree

Lines changed: 290 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,290 @@
1+
import assert from 'node:assert/strict';
2+
import { afterEach, test, vi } from 'vitest';
3+
4+
// Every claim the stopper makes is about what the host answers, so one double answers both syscalls it
5+
// reads: `kill(pid, signal)` for the signals and liveness probes, and `ps` for the identity fields.
6+
// One host state drives both, so no case can be live while its identity says otherwise.
7+
const { mockRunCmd } = vi.hoisted(() => ({ mockRunCmd: vi.fn() }));
8+
vi.mock('./exec.ts', async () => ({
9+
...(await vi.importActual<typeof import('./exec.ts')>('./exec.ts')),
10+
runCmd: mockRunCmd,
11+
}));
12+
13+
import {
14+
stopProcessAndConfirmExit,
15+
type ConfirmedProcessStop,
16+
type ProcessStopTarget,
17+
} from './host-process.ts';
18+
19+
const PID = 4242;
20+
const BUDGET = { termTimeoutMs: 1_000, killTimeoutMs: 500 };
21+
type Signal = 'SIGTERM' | 'SIGKILL';
22+
23+
const START = 'Mon Oct 12 00:00:00 2026';
24+
const OTHER_START = 'Tue Oct 13 09:00:00 2026';
25+
const COMMAND = '/usr/bin/node /app/dist/src/client/companion-tunnel.js --run-metro-companion';
26+
27+
const STOPPED: ConfirmedProcessStop = { status: 'stopped' };
28+
/** `ps` found the row and told nothing for that column, which is unknown rather than absent. */
29+
const EMPTY = { stdout: '', stderr: '', exitCode: 0 };
30+
const PS_REFUSED = { stdout: '', stderr: 'ps: not permitted', exitCode: 1 };
31+
const psAnswer = (value: string) => ({ stdout: `${value}\n`, stderr: '', exitCode: 0 });
32+
const refused = (signal: Signal): ConfirmedProcessStop => ({
33+
status: 'retained',
34+
reason: 'signal-failed',
35+
signal,
36+
errno: 'EPERM',
37+
});
38+
39+
/** What the host will say about the pid, overriding what the recorded process would show. */
40+
type HostIdentity = Readonly<{ startTime?: string | null; command?: string | null }>;
41+
42+
type HostCase = Readonly<{
43+
name: string;
44+
/** Whether the caller recorded what would let it name the process; defaults to having recorded it. */
45+
recorded?: boolean;
46+
/** What the host answers each signal with: a string is the refusing errno, absent accepts. */
47+
answers?: Partial<Record<Signal, string>>;
48+
/** The signal after which the process has run its course, when it ends because it was asked. */
49+
exitsOnSignal?: Signal;
50+
/** How many liveness probes it survives before somebody else ends it. */
51+
exitsAfterProbes?: number;
52+
/**
53+
* How a process that has run its course keeps answering to its pid, which is where liveness and
54+
* identity disagree: a POSIX zombie answers `EPERM` beside a `Z` row. `'held'` never lets go.
55+
*/
56+
afterExit?: 'zombie' | 'held';
57+
identity?: HostIdentity;
58+
/** A `ps` the host refuses outright, so identity cannot be read at all. */
59+
psFails?: boolean;
60+
/** The signals the stop must spend, in order, and the verdict each host answer earns. */
61+
expect: { outcome: ConfirmedProcessStop; signals: Signal[] };
62+
}>;
63+
64+
type HostModel = Omit<HostCase, 'name' | 'expect'>;
65+
type Expect = HostCase['expect'];
66+
const HELD = { afterExit: 'held' } satisfies HostModel;
67+
const DENIED_ON_TERM = { answers: { SIGTERM: 'EPERM' } } satisfies HostModel;
68+
const UNREADABLE = { identity: { startTime: null, command: null } } satisfies HostModel;
69+
/** The process has run its course: liveness stops answering for it before anything is signaled. */
70+
const GONE = { exitsAfterProbes: 0 } satisfies HostModel;
71+
const ZOMBIE = { ...GONE, afterExit: 'zombie' } satisfies HostModel;
72+
const STOPPED_BY_TERM: Expect = { outcome: STOPPED, signals: ['SIGTERM'] };
73+
const STOPPED_BY_KILL: Expect = { outcome: STOPPED, signals: ['SIGTERM', 'SIGKILL'] };
74+
const NEVER_SIGNALED: Expect = { outcome: STOPPED, signals: [] };
75+
const REFUSED_ON_TERM: Expect = { outcome: refused('SIGTERM'), signals: ['SIGTERM'] };
76+
const REFUSED_ON_KILL: Expect = { outcome: refused('SIGKILL'), signals: STOPPED_BY_KILL.signals };
77+
const EXIT_TIMED_OUT: Expect = {
78+
outcome: { status: 'retained', reason: 'exit-timeout', signal: 'SIGKILL' },
79+
signals: STOPPED_BY_KILL.signals,
80+
};
81+
const UNVERIFIED: Expect = {
82+
outcome: { status: 'retained', reason: 'identity-unverified' },
83+
signals: [],
84+
};
85+
86+
const STOP_CASES: HostCase[] = [
87+
// A caller that recorded nothing about the pid cannot name the process at all, so no signal is
88+
// spent on it: the pid is retained rather than handed to whatever holds it now.
89+
{ name: 'is a pid nobody recorded anything about', recorded: false, ...HELD, expect: UNVERIFIED },
90+
91+
// Escalation, refusal and the two ways a signal stage proves the exit.
92+
{ name: 'leaves on SIGTERM', exitsOnSignal: 'SIGTERM', expect: STOPPED_BY_TERM },
93+
{
94+
name: 'ignores SIGTERM and takes SIGKILL',
95+
exitsOnSignal: 'SIGKILL',
96+
expect: STOPPED_BY_KILL,
97+
},
98+
{ name: 'was gone before anything was signaled', ...GONE, expect: NEVER_SIGNALED },
99+
{
100+
name: 'is held by another owner',
101+
...DENIED_ON_TERM,
102+
...HELD,
103+
expect: REFUSED_ON_TERM,
104+
},
105+
{
106+
name: 'refuses SIGKILL',
107+
answers: { SIGKILL: 'EPERM' },
108+
...HELD,
109+
expect: REFUSED_ON_KILL,
110+
},
111+
{
112+
name: 'is released inside the budget',
113+
...DENIED_ON_TERM,
114+
exitsAfterProbes: 3,
115+
expect: STOPPED_BY_TERM,
116+
},
117+
{
118+
// Liveness keeps answering for a zombie that outlives its budget, so only the `Z` row proves
119+
// the recorded process is gone, and it does that after the wait rather than before the signal.
120+
name: 'leaves a zombie the budget cannot wait out',
121+
exitsOnSignal: 'SIGTERM',
122+
afterExit: 'zombie',
123+
expect: STOPPED_BY_TERM,
124+
},
125+
{ name: 'outlives both budgets', ...HELD, expect: EXIT_TIMED_OUT },
126+
127+
// What the recorded identity buys: a stale pid is proven without signaling it, and a host that
128+
// will not describe the pid stops the stopper instead of authorizing a blind signal.
129+
{
130+
name: 'left a zombie before anything was signaled',
131+
...ZOMBIE,
132+
expect: NEVER_SIGNALED,
133+
},
134+
{
135+
// Windows hides only the command line of an elevated or other-user process, and that is the #3540
136+
// companion: it must be signaled and retained, never reported stopped.
137+
name: 'recorded process hides its command line, as an elevated one does',
138+
identity: { command: null },
139+
...DENIED_ON_TERM,
140+
...HELD,
141+
expect: REFUSED_ON_TERM,
142+
},
143+
{
144+
name: 'recorded process hides its start time',
145+
identity: { startTime: null },
146+
...DENIED_ON_TERM,
147+
...HELD,
148+
expect: REFUSED_ON_TERM,
149+
},
150+
{
151+
// POSIX `hidepid`, a `ps` that times out, or a Windows process that exited while its object still
152+
// had handles: the pid answers `kill(pid, 0)` and nothing else, which is unknown, not absent.
153+
name: 'live recorded pid the host will not describe',
154+
...UNREADABLE,
155+
...HELD,
156+
expect: UNVERIFIED,
157+
},
158+
{
159+
name: 'live recorded pid whose process tool the host refuses',
160+
psFails: true,
161+
...HELD,
162+
expect: UNVERIFIED,
163+
},
164+
{
165+
name: 'pid the host has handed to another lifetime',
166+
identity: { startTime: OTHER_START },
167+
expect: NEVER_SIGNALED,
168+
},
169+
{
170+
name: 'pid whose command line names a different program',
171+
identity: { command: '/usr/bin/other --serve' },
172+
expect: NEVER_SIGNALED,
173+
},
174+
];
175+
176+
function driveHost(model: HostCase): { signals: Signal[] } {
177+
const signals: Signal[] = [];
178+
let ended = false;
179+
let probes = 0;
180+
const hasEnded = () =>
181+
ended ||
182+
(model.afterExit !== 'held' && probes >= (model.exitsAfterProbes ?? Number.POSITIVE_INFINITY));
183+
vi.spyOn(process, 'kill').mockImplementation(((_pid: number, signal: string | number) => {
184+
if (signal === 0) {
185+
probes += 1;
186+
// A released pid answers `ESRCH`. A zombie, and on Windows a process whose object still has
187+
// handles, both keep answering `EPERM`, and only the process table tells those apart.
188+
if (hasEnded() && model.afterExit === undefined)
189+
throw Object.assign(new Error('no such process'), { code: 'ESRCH' });
190+
if (hasEnded()) throw Object.assign(new Error('operation not permitted'), { code: 'EPERM' });
191+
return true;
192+
}
193+
const name = signal as Signal;
194+
signals.push(name);
195+
const errno = model.answers?.[name];
196+
if (errno) throw Object.assign(new Error(`kill refused: ${errno}`), { code: errno });
197+
if (model.exitsOnSignal === name) ended = true;
198+
return true;
199+
}) as typeof process.kill);
200+
201+
// Absent means the recorded process, `null` means the host withholds the column, and a string is
202+
// what it says instead.
203+
const identity = {
204+
startTime: model.identity?.startTime === undefined ? START : model.identity.startTime,
205+
command: model.identity?.command === undefined ? COMMAND : model.identity.command,
206+
};
207+
mockRunCmd.mockImplementation(async (_command: string, args: readonly string[]) => {
208+
if (model.psFails) return PS_REFUSED;
209+
// A process the host has fully released, and one that left no row, both answer no fields.
210+
if (hasEnded() && model.afterExit !== 'zombie') return EMPTY;
211+
const field = String(args[3]);
212+
if (field === 'state=') return psAnswer(hasEnded() && model.afterExit === 'zombie' ? 'Z' : 'S');
213+
// Withheld is its own answer: `ps` finds the row and reports nothing for that column, which is
214+
// how Windows answers `CommandLine` for another user's process.
215+
const column = field === 'lstart=' ? identity.startTime : identity.command;
216+
return column === null ? EMPTY : psAnswer(column);
217+
});
218+
return { signals };
219+
}
220+
221+
function targetOf(model: HostCase): ProcessStopTarget {
222+
return {
223+
pid: PID,
224+
identity: model.recorded === false ? {} : { startTime: START, matches: (c) => c === COMMAND },
225+
};
226+
}
227+
228+
afterEach(() => {
229+
vi.useRealTimers();
230+
vi.restoreAllMocks();
231+
mockRunCmd.mockReset();
232+
});
233+
234+
// The host model above answers with POSIX `ps` fields; a Windows host answers the same questions from
235+
// CIM, which never reports a zombie state. win32 branches live in host-process-windows.test.ts.
236+
test.skipIf(process.platform === 'win32').each(STOP_CASES)(
237+
'stopProcessAndConfirmExit $name',
238+
async (testCase) => {
239+
const host = driveHost(testCase);
240+
// Both stage budgets, advanced on a fake clock: a retained outcome must not cost real time.
241+
vi.useFakeTimers();
242+
const stop = stopProcessAndConfirmExit(targetOf(testCase), BUDGET);
243+
await vi.advanceTimersByTimeAsync(BUDGET.termTimeoutMs + BUDGET.killTimeoutMs);
244+
245+
assert.deepEqual(await stop, testCase.expect.outcome);
246+
assert.deepEqual(host.signals, testCase.expect.signals);
247+
},
248+
);
249+
250+
// `kill(0, SIGTERM)` addresses this very process group, so an unvalidated pid must not reach it.
251+
test.each([0, -1, 1.5, Number.NaN])(
252+
'never signals a pid that is not a process: %s',
253+
async (pid) => {
254+
const signals: string[] = [];
255+
vi.spyOn(process, 'kill').mockImplementation(((_pid: number, signal: string) => {
256+
signals.push(signal);
257+
throw Object.assign(new Error('no such process'), { code: 'ESRCH' });
258+
}) as typeof process.kill);
259+
assert.deepEqual(await stopProcessAndConfirmExit({ pid, identity: {} }, BUDGET), STOPPED);
260+
assert.deepEqual(signals, []);
261+
},
262+
);
263+
264+
// Stale or malformed process state can name the caller's own pid, and SIGTERM would end the very
265+
// process trying to stop it.
266+
test('refuses to stop the current process', async () => {
267+
const signals: string[] = [];
268+
vi.spyOn(process, 'kill').mockImplementation(((_pid: number, signal: string) => {
269+
signals.push(signal);
270+
return true;
271+
}) as typeof process.kill);
272+
await assert.rejects(
273+
() => stopProcessAndConfirmExit({ pid: process.pid, identity: {} }, BUDGET),
274+
RangeError,
275+
);
276+
assert.deepEqual(signals, []);
277+
});
278+
279+
// Node's own argument faults carry a `code` that is not an errno, and reading one as a refusal would
280+
// send the caller off to stop a process that never existed. The fault itself has to reach it.
281+
test('propagates an argument fault instead of reporting it as a host refusal', async () => {
282+
const failure = Object.assign(new TypeError('bad signal'), { code: 'ERR_INVALID_ARG_TYPE' });
283+
vi.spyOn(process, 'kill').mockImplementation(() => {
284+
throw failure;
285+
});
286+
const settled = await stopProcessAndConfirmExit({ pid: PID, identity: {} }, BUDGET).catch(
287+
(error: unknown) => error,
288+
);
289+
assert.equal(settled, failure);
290+
});

0 commit comments

Comments
 (0)