Skip to content

Commit 7d4b8f3

Browse files
fix(host-kit): a reclaimed lock is proven to be the one judged stale before removal
A rename addresses whatever stands at the lock path now, not the directory whose record was read. A contender that reclaimed first and published a live owner in the meantime had its live directory moved aside by the loser and then removed, which handed the same lock to two holders. What arrives is now compared against what was judged — same inode, and no live owner inside — and a directory that turns out to belong to someone else is renamed back rather than deleted. `releaseProcessLock` can now refuse to clear a lock it cannot prove it owns, so the callers that run a task under a lock stop letting that verdict displace the task's own failure: the unverifiable release is reported when the task succeeded, and suppressed when the task already failed, because the lock's stale-clear path resolves a lock that is still standing while nothing else recovers why the task failed. The abandoned cache-lock acquire releases without leaving a rejected promise nobody awaits. Co-authored-by: Apex by Callstack <[email protected]>
1 parent 2ec6027 commit 7d4b8f3

9 files changed

Lines changed: 246 additions & 28 deletions

File tree

‎packages/capture-kit/src/recording/swift-cache.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -128,7 +128,9 @@ async function ensureSwiftExecutable(params: {
128128
fs.renameSync(tempExecutablePath, params.executablePath);
129129
} finally {
130130
fs.rmSync(tempDir, { recursive: true, force: true });
131-
await releaseLock();
131+
// The build's own failure is the reportable fact; an unverified release leaves the
132+
// lock to the stale-clear path rather than displacing it.
133+
await releaseLock().catch(() => undefined);
132134
}
133135
}
134136

‎packages/host-kit/src/internal/process-lock.test.ts‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -411,6 +411,67 @@ test('a reclaim that cannot remove the directory it moved aside still holds the
411411
}
412412
});
413413

414+
test('a live owner published between the stale read and the rename keeps its lock', async () => {
415+
const lockDirPath = path.join(tmpDir, 'stolen-race.lock');
416+
const ownerFilePath = path.join(lockDirPath, 'owner.json');
417+
fs.mkdirSync(lockDirPath);
418+
fs.writeFileSync(
419+
ownerFilePath,
420+
JSON.stringify({ pid: 999_999_999, startTime: null, acquiredAtMs: Date.now() }),
421+
);
422+
stampDirectoryAbandoned(lockDirPath);
423+
424+
// The dead record is read, and before the rename lands another contender reclaims the
425+
// path, publishes itself, and goes live. The rename then moves that live directory, and
426+
// the only thing that can tell it apart from the one judged abandoned is the directory
427+
// itself.
428+
let republished = false;
429+
const realRename = fs.renameSync;
430+
const renameSpy = vi.spyOn(fs, 'renameSync').mockImplementation(((
431+
from: fs.PathLike,
432+
to: fs.PathLike,
433+
) => {
434+
if (!String(to).includes(RECLAIMED_MARK) || republished) return realRename(from, to);
435+
republished = true;
436+
fs.rmSync(String(from), { recursive: true, force: true });
437+
fs.mkdirSync(String(from));
438+
fs.writeFileSync(path.join(String(from), 'owner.json'), JSON.stringify(currentProcessOwner()));
439+
return realRename(from, to);
440+
}) as typeof fs.renameSync);
441+
442+
try {
443+
await assert.rejects(
444+
() =>
445+
acquireProcessLock({
446+
lockDirPath,
447+
owner: { pid: 999_999_998, startTime: null, acquiredAtMs: Date.now() },
448+
timeoutMs: 50,
449+
pollMs: 1,
450+
}),
451+
(error: unknown) => {
452+
assert.ok(error instanceof AppError);
453+
assert.equal(error.details?.ownerLiveness, 'live');
454+
assert.equal(error.details?.ownerPid, process.pid);
455+
return true;
456+
},
457+
);
458+
assert.equal(republished, true);
459+
assert.equal(
460+
(JSON.parse(fs.readFileSync(ownerFilePath, 'utf8')) as { pid: number }).pid,
461+
process.pid,
462+
);
463+
assert.deepEqual(
464+
fs
465+
.readdirSync(tmpDir)
466+
.filter((name) => name.includes(RECLAIMED_MARK))
467+
.sort(),
468+
[],
469+
);
470+
} finally {
471+
renameSpy.mockRestore();
472+
}
473+
});
474+
414475
test('a reclaim whose directory another contender moved aside retries and acquires', async () => {
415476
const lockDirPath = path.join(tmpDir, 'lost-race.lock');
416477
fs.mkdirSync(lockDirPath);

‎packages/host-kit/src/internal/process-lock.ts‎

Lines changed: 64 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import { publishFileSync } from './atomic-file.ts';
66
import { classifyOwnerLiveness, ownerIdentityMatches } from './owner-identity.ts';
77
import { sleep } from './timeouts.ts';
88

9+
const OWNER_FILE_NAME = 'owner.json';
910
const DEFAULT_LOCK_TIMEOUT_MS = 30_000;
1011
const DEFAULT_LOCK_POLL_MS = 100;
1112
const DEFAULT_LOCK_OWNER_GRACE_MS = 5_000;
@@ -31,7 +32,7 @@ export async function acquireProcessLock(params: {
3132
description?: string;
3233
}): Promise<() => Promise<void>> {
3334
const { lockDirPath, owner } = params;
34-
const ownerFilePath = path.join(lockDirPath, 'owner.json');
35+
const ownerFilePath = path.join(lockDirPath, OWNER_FILE_NAME);
3536
const deadline = Date.now() + (params.timeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS);
3637
const pollMs = params.pollMs ?? DEFAULT_LOCK_POLL_MS;
3738
const ownerGraceMs = params.ownerGraceMs ?? DEFAULT_LOCK_OWNER_GRACE_MS;
@@ -124,7 +125,7 @@ function clearStaleProcessLock(
124125
// owner record, so its age is the only evidence available about it.
125126
if (!lockStats.isDirectory()) {
126127
return reclaimWhenAbandoned(lockStats, ownerGraceMs)
127-
? reclaimProcessLockDirectory(lockDirPath, ownerFilePath)
128+
? reclaimProcessLockDirectory(lockDirPath, ownerFilePath, lockStats)
128129
: false;
129130
}
130131

@@ -133,7 +134,7 @@ function clearStaleProcessLock(
133134
if (isLiveProcessLockOwner(reading.owner)) {
134135
return false;
135136
}
136-
return reclaimProcessLockDirectory(lockDirPath, ownerFilePath);
137+
return reclaimProcessLockDirectory(lockDirPath, ownerFilePath, lockStats);
137138
}
138139
// A record we cannot read leaves an owner whose identity is unknown, which is not
139140
// evidence of death. Only a record that is genuinely absent lets the directory's
@@ -142,7 +143,7 @@ function clearStaleProcessLock(
142143
return false;
143144
}
144145
return reclaimWhenAbandoned(lockStats, ownerGraceMs)
145-
? reclaimProcessLockDirectory(lockDirPath, ownerFilePath)
146+
? reclaimProcessLockDirectory(lockDirPath, ownerFilePath, lockStats)
146147
: false;
147148
}
148149

@@ -156,30 +157,75 @@ function reclaimWhenAbandoned(lockStats: fs.Stats, ownerGraceMs: number): boolea
156157
* the caller's side: the second succeeds silently on the path the first already
157158
* cleared, and both contenders continue as though they had freed the lock. `mkdir`'s
158159
* `EEXIST`, unchanged, stays the arbiter of the lock itself.
159-
*
160-
* A win32 directory with a handle open inside it refuses the rename and often the
161-
* removal too, which is why a forced removal remains as the fallback: stale-clear
162-
* atomicity is best effort there and exact elsewhere. The fallback re-reads the
163-
* record first, because a refused rename means time passed and a live contender may
164-
* have claimed the path in it.
165160
*/
166-
function reclaimProcessLockDirectory(lockDirPath: string, ownerFilePath: string): boolean {
161+
function reclaimProcessLockDirectory(
162+
lockDirPath: string,
163+
ownerFilePath: string,
164+
judged: fs.Stats,
165+
): boolean {
167166
const asidePath = reclaimedLockPath(lockDirPath);
168167
try {
169168
fs.renameSync(lockDirPath, asidePath);
170169
} catch (error) {
171-
const code = (error as NodeJS.ErrnoException | null)?.code;
172-
if (code === 'ENOENT') return true;
173-
if (code !== 'EPERM' && code !== 'EACCES' && code !== 'ENOTEMPTY') return false;
174-
const reading = readProcessLockOwner(ownerFilePath);
175-
if (reading.kind === 'owner' && isLiveProcessLockOwner(reading.owner)) return false;
176-
fs.rmSync(lockDirPath, { recursive: true, force: true });
177-
return true;
170+
return reclaimWithoutTheRename(lockDirPath, ownerFilePath, error);
171+
}
172+
if (!reclaimedLockIsTheOneJudged(asidePath, judged)) {
173+
restoreReclaimedLockDirectory(asidePath, lockDirPath);
174+
return false;
178175
}
179176
removeReclaimedLockDirectory(asidePath);
180177
return true;
181178
}
182179

180+
/**
181+
* A win32 directory with a handle open inside it refuses the rename and often the removal
182+
* too, which is why a forced removal remains as the fallback: stale-clear atomicity is
183+
* best effort there and exact elsewhere. The fallback re-reads the record first, because a
184+
* refused rename means time passed and a live contender may have claimed the path in it.
185+
*/
186+
function reclaimWithoutTheRename(
187+
lockDirPath: string,
188+
ownerFilePath: string,
189+
renameError: unknown,
190+
): boolean {
191+
const code = (renameError as NodeJS.ErrnoException | null)?.code;
192+
if (code === 'ENOENT') return true;
193+
if (code !== 'EPERM' && code !== 'EACCES' && code !== 'ENOTEMPTY') return false;
194+
const reading = readProcessLockOwner(ownerFilePath);
195+
if (reading.kind === 'owner' && isLiveProcessLockOwner(reading.owner)) return false;
196+
fs.rmSync(lockDirPath, { recursive: true, force: true });
197+
return true;
198+
}
199+
200+
/**
201+
* A rename addresses whatever stands at the path now, not the directory whose record was
202+
* read. A contender that reclaimed first and published a live owner in the meantime has
203+
* put a different directory there, so what arrived is compared against what was judged:
204+
* the same inode, and no live owner inside.
205+
*/
206+
function reclaimedLockIsTheOneJudged(asidePath: string, judged: fs.Stats): boolean {
207+
let moved: fs.Stats;
208+
try {
209+
moved = fs.statSync(asidePath);
210+
} catch {
211+
return false;
212+
}
213+
if (moved.ino !== judged.ino || moved.dev !== judged.dev) return false;
214+
const reading = readProcessLockOwner(path.join(asidePath, OWNER_FILE_NAME));
215+
return !(reading.kind === 'owner' && isLiveProcessLockOwner(reading.owner));
216+
}
217+
218+
/**
219+
* Returns a directory that turned out to belong to someone else. Failure is not a
220+
* licence to delete it: its holder's own release reports an unreadable owner rather than
221+
* let this process clear a lock it does not own.
222+
*/
223+
function restoreReclaimedLockDirectory(asidePath: string, lockDirPath: string): void {
224+
try {
225+
fs.renameSync(asidePath, lockDirPath);
226+
} catch {}
227+
}
228+
183229
/** Janitorial work after the rename already achieved the exclusion. */
184230
function removeReclaimedLockDirectory(asidePath: string): void {
185231
try {
Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
import assert from 'node:assert/strict';
2+
import fs from 'node:fs';
3+
import { afterEach, test, vi } from 'vitest';
4+
import { AppError } from '@agent-device/kernel/errors';
5+
import { withRunnerLeaseLock } from '../runner-lease.ts';
6+
import { mkdtempForTestSync } from './tmp-dir.ts';
7+
8+
// A release that cannot read far enough to prove ownership leaves the lock standing and
9+
// says so. That verdict is worth reporting when the task succeeded, and worth suppressing
10+
// when the task already failed: the lock's own stale-clear path resolves a lock that is
11+
// still standing, while nothing else recovers the reason the task failed.
12+
13+
const DEVICE_ID = 'release-ownership-runner';
14+
15+
let leaseRoot = '';
16+
17+
afterEach(() => {
18+
vi.restoreAllMocks();
19+
delete process.env.AGENT_DEVICE_IOS_RUNNER_LEASE_DIR;
20+
fs.rmSync(leaseRoot, { recursive: true, force: true });
21+
});
22+
23+
function armUnverifiableRelease(root: string): () => void {
24+
const originalReadFileSync = fs.readFileSync;
25+
let armed = false;
26+
vi.spyOn(fs, 'readFileSync').mockImplementation(((
27+
...args: Parameters<typeof fs.readFileSync>
28+
) => {
29+
const target = args[0];
30+
if (
31+
armed &&
32+
typeof target === 'string' &&
33+
target.startsWith(root) &&
34+
target.endsWith('owner.json')
35+
) {
36+
throw Object.assign(new Error('injected owner record i/o'), { code: 'EIO' });
37+
}
38+
return Reflect.apply(originalReadFileSync, fs, args);
39+
}) as typeof fs.readFileSync);
40+
return () => {
41+
armed = true;
42+
};
43+
}
44+
45+
function beginLeaseRoot(): string {
46+
leaseRoot = mkdtempForTestSync('agent-device-lease-release-ownership-');
47+
process.env.AGENT_DEVICE_IOS_RUNNER_LEASE_DIR = leaseRoot;
48+
return leaseRoot;
49+
}
50+
51+
test('a failed lease task outranks an unverifiable release', async () => {
52+
const root = beginLeaseRoot();
53+
const arm = armUnverifiableRelease(root);
54+
const taskFailure = new Error('the lease task failed');
55+
56+
await assert.rejects(
57+
() =>
58+
withRunnerLeaseLock(DEVICE_ID, async () => {
59+
arm();
60+
throw taskFailure;
61+
}),
62+
(error: unknown) => {
63+
assert.equal(error, taskFailure);
64+
return true;
65+
},
66+
);
67+
});
68+
69+
test('a lease lock that cannot be verified at release is reported and left standing', async () => {
70+
const root = beginLeaseRoot();
71+
const arm = armUnverifiableRelease(root);
72+
73+
await assert.rejects(
74+
() =>
75+
withRunnerLeaseLock(DEVICE_ID, async () => {
76+
arm();
77+
return 'done';
78+
}),
79+
(error: unknown) => {
80+
assert.ok(error instanceof AppError);
81+
assert.equal(error.details?.ownerReleaseUnverified, true);
82+
return true;
83+
},
84+
);
85+
86+
assert.deepEqual(fs.readdirSync(root), [`${DEVICE_ID}.json.lock`]);
87+
});

‎packages/platform-apple/src/runner/runner-device-set.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,9 @@ export async function acquireXcodebuildSimulatorSetRedirect(
9999
xctestDeviceSetPath,
100100
backupPath,
101101
});
102-
await releaseLock();
102+
// The redirect failure is the reportable fact; an unverified release leaves the lock
103+
// to the stale-clear path rather than displacing it.
104+
await releaseLock().catch(() => undefined);
103105
throw new AppError('COMMAND_FAILED', 'Failed to redirect XCTest device set path', {
104106
requestedSetPath,
105107
xctestDeviceSetPath,

‎packages/platform-apple/src/runner/runner-lease.ts‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -127,9 +127,14 @@ export async function withRunnerLeaseLock<T>(deviceId: string, task: () => Promi
127127
description: `iOS runner lease for ${deviceId}`,
128128
});
129129
try {
130-
return await task();
131-
} finally {
130+
const result = await task();
132131
await release();
132+
return result;
133+
} catch (error) {
134+
// A task that failed is the reportable fact; an unverified release only says the
135+
// lease lock is still standing, which the stale-clear path resolves on its own.
136+
await release().catch(() => undefined);
137+
throw error;
133138
}
134139
}
135140

‎packages/platform-apple/src/snapshot-source/host.ts‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -195,11 +195,16 @@ async function acquireSnapshotSourceLock(
195195
try {
196196
return await Promise.race([pending, aborted]);
197197
} catch (error) {
198-
if (canceled)
198+
if (canceled) {
199+
// The task is abandoned, so its lock is released best effort. A release that
200+
// cannot prove ownership leaves the lock to the stale-clear path, which is the
201+
// outcome this branch already accepts; it must not arrive as an unhandled
202+
// rejection on a promise nobody is awaiting any more.
199203
void pending.then(
200-
(release) => release(),
204+
(release) => release().catch(() => undefined),
201205
() => undefined,
202206
);
207+
}
203208
if (
204209
deadline.clock.isExpired() &&
205210
!(error instanceof SnapshotSourceError && error.failureKind === 'cancelled')

‎packages/platform-web/src/agent-browser-tool.ts‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -101,9 +101,14 @@ export async function setupManagedAgentBrowser(options: {
101101
packageName: AGENT_BROWSER,
102102
version: MANAGED_AGENT_BROWSER_VERSION,
103103
});
104-
return getManagedAgentBrowserStatus(options);
105-
} finally {
104+
const status = await getManagedAgentBrowserStatus(options);
106105
await release();
106+
return status;
107+
} catch (error) {
108+
// A failed install is the reportable fact; an unverified release leaves the lock to
109+
// the stale-clear path.
110+
await release().catch(() => undefined);
111+
throw error;
107112
}
108113
}
109114

‎src/daemon/device-claim-store.ts‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,13 @@ export async function withDeviceClaimLock<T>(
3232
description: `device claim for ${deviceKey}`,
3333
});
3434
try {
35-
return await task();
36-
} finally {
35+
const result = await task();
3736
await release();
37+
return result;
38+
} catch (error) {
39+
// A task that failed is the reportable fact; an unverified release only says the
40+
// lock is still standing, which the stale-clear path resolves on its own.
41+
await release().catch(() => undefined);
42+
throw error;
3843
}
3944
}

0 commit comments

Comments
 (0)