Skip to content

Commit 328576e

Browse files
committed
fix: add exclusive file lock to updateState for concurrency safety
updateState's read-modify-write cycle was not protected against concurrent companion processes (background worker + status/cancel handler), which could silently lose each other's writes. Acquire an exclusive lock file (state.json.lock via O_EXCL) before reading, hold it through mutation and write, release in finally. Stale locks older than 30s are evicted. Blocks up to 5s with retry. Closes the pre-existing concurrency race amplified by PR #51's dead-PID reconciliation (which adds upsertJob calls on every status read).
1 parent d299b96 commit 328576e

2 files changed

Lines changed: 246 additions & 10 deletions

File tree

‎plugins/opencode/scripts/lib/state.mjs‎

Lines changed: 97 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,9 @@ const FALLBACK_STATE_ROOT_DIR = path.join(os.tmpdir(), "opencode-companion");
1414
const MIGRATION_LOCK_STALE_MS = 5 * 60 * 1000;
1515
const MIGRATION_WAIT_MS = 2000;
1616
const PATH_KEYS = new Set(["logFile", "dataFile"]);
17+
const STATE_LOCK_STALE_MS = 30_000;
18+
const STATE_LOCK_WAIT_MS = 5_000;
19+
const STATE_LOCK_RETRY_MS = 50;
1720

1821
function workspaceHash(workspacePath) {
1922
return crypto.createHash("sha256").update(workspacePath).digest("hex").slice(0, 16);
@@ -209,15 +212,92 @@ function stateFile(root) {
209212
return path.join(root, "state.json");
210213
}
211214

215+
/**
216+
* Acquire an exclusive lock on the state file for a given root directory.
217+
* Uses a sibling `.lock` file created with O_EXCL. Stale locks older than
218+
* STATE_LOCK_STALE_MS are forcibly removed. Blocks up to STATE_LOCK_WAIT_MS
219+
* with STATE_LOCK_RETRY_MS intervals.
220+
*
221+
* @param {string} root - the stateRoot directory
222+
* @returns {{ fd: number, lockPath: string }}
223+
*/
224+
function acquireStateLock(root) {
225+
const lockPath = stateFile(root) + ".lock";
226+
ensureDir(path.dirname(lockPath));
227+
228+
const deadline = Date.now() + STATE_LOCK_WAIT_MS;
229+
230+
while (true) {
231+
try {
232+
const fd = fs.openSync(lockPath, "wx");
233+
try {
234+
fs.writeSync(fd, `${process.pid}\n${new Date().toISOString()}\n`);
235+
} catch {}
236+
return { fd, lockPath };
237+
} catch (err) {
238+
if (err?.code !== "EEXIST") throw err;
239+
240+
try {
241+
const stat = fs.statSync(lockPath);
242+
if (Date.now() - stat.mtimeMs > STATE_LOCK_STALE_MS) {
243+
fs.rmSync(lockPath, { force: true });
244+
continue;
245+
}
246+
} catch (statErr) {
247+
if (statErr?.code !== "ENOENT") throw statErr;
248+
continue;
249+
}
250+
251+
if (Date.now() >= deadline) {
252+
throw new Error(
253+
`Timed out waiting for state lock after ${Math.round(STATE_LOCK_WAIT_MS / 1000)}s: ${lockPath}. ` +
254+
"If no other companion process is running, delete the lock file manually."
255+
);
256+
}
257+
258+
sleepSync(STATE_LOCK_RETRY_MS);
259+
}
260+
}
261+
}
262+
263+
/**
264+
* Release a state lock previously acquired by acquireStateLock.
265+
* @param {{ fd: number | null, lockPath: string } | null} lock
266+
*/
267+
function releaseStateLock(lock) {
268+
if (!lock) return;
269+
if (lock.fd != null) {
270+
try { fs.closeSync(lock.fd); } catch {}
271+
}
272+
try { fs.rmSync(lock.lockPath, { force: true }); } catch {}
273+
}
274+
275+
/**
276+
* Load state from an already-resolved root directory (no migration check).
277+
* @param {string} root
278+
* @returns {{ config: object, jobs: object[] }}
279+
*/
280+
function loadStateFromRoot(root) {
281+
const data = readJson(stateFile(root));
282+
return data ?? { config: {}, jobs: [] };
283+
}
284+
285+
/**
286+
* Save state to an already-resolved root directory (no migration check).
287+
* @param {string} root
288+
* @param {object} state
289+
*/
290+
function saveStateToRoot(root, state) {
291+
writeJson(stateFile(root), state);
292+
}
293+
212294
/**
213295
* Load the state for a workspace.
214296
* @param {string} workspacePath
215297
* @returns {{ config: object, jobs: object[] }}
216298
*/
217299
export function loadState(workspacePath) {
218-
const root = stateRoot(workspacePath);
219-
const data = readJson(stateFile(root));
220-
return data ?? { config: {}, jobs: [] };
300+
return loadStateFromRoot(stateRoot(workspacePath));
221301
}
222302

223303
/**
@@ -226,21 +306,28 @@ export function loadState(workspacePath) {
226306
* @param {object} state
227307
*/
228308
export function saveState(workspacePath, state) {
229-
const root = stateRoot(workspacePath);
230-
writeJson(stateFile(root), state);
309+
saveStateToRoot(stateRoot(workspacePath), state);
231310
}
232311

233312
/**
234-
* Update the state atomically using a mutator function.
313+
* Update the state atomically using a mutator function. Acquires an
314+
* exclusive file lock for the read-modify-write cycle so concurrent
315+
* companion processes cannot lose each other's writes.
235316
* @param {string} workspacePath
236317
* @param {(state: object) => void} mutator
237318
* @returns {object} the updated state
238319
*/
239320
export function updateState(workspacePath, mutator) {
240-
const state = loadState(workspacePath);
241-
mutator(state);
242-
saveState(workspacePath, state);
243-
return state;
321+
const root = stateRoot(workspacePath);
322+
const lock = acquireStateLock(root);
323+
try {
324+
const state = loadStateFromRoot(root);
325+
mutator(state);
326+
saveStateToRoot(root, state);
327+
return state;
328+
} finally {
329+
releaseStateLock(lock);
330+
}
244331
}
245332

246333
/**

‎tests/state-lock.test.mjs‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
import { describe, it, beforeEach, afterEach } from "node:test";
2+
import assert from "node:assert/strict";
3+
import { fork } from "node:child_process";
4+
import fs from "node:fs";
5+
import os from "node:os";
6+
import path from "node:path";
7+
import { fileURLToPath } from "node:url";
8+
import { createTmpDir, cleanupTmpDir, setupTestEnv } from "./helpers.mjs";
9+
import {
10+
loadState,
11+
updateState,
12+
upsertJob,
13+
stateRoot,
14+
} from "../plugins/opencode/scripts/lib/state.mjs";
15+
16+
const __dirname = path.dirname(fileURLToPath(import.meta.url));
17+
const stateModulePath = path.resolve(__dirname, "..", "plugins", "opencode", "scripts", "lib", "state.mjs");
18+
19+
let tmpDir;
20+
const workspace = "/lock-test/workspace";
21+
22+
beforeEach(() => {
23+
tmpDir = createTmpDir("state-lock-");
24+
setupTestEnv(tmpDir);
25+
});
26+
27+
afterEach(() => {
28+
cleanupTmpDir(tmpDir);
29+
});
30+
31+
describe("updateState lock", () => {
32+
it("creates and removes a lock file during updateState", () => {
33+
updateState(workspace, (state) => {
34+
const root = stateRoot(workspace);
35+
const lockPath = path.join(root, "state.json.lock");
36+
assert.ok(
37+
fs.existsSync(lockPath),
38+
"lock file should exist while mutator is running"
39+
);
40+
state.config.test = true;
41+
});
42+
43+
const root = stateRoot(workspace);
44+
const lockPath = path.join(root, "state.json.lock");
45+
assert.ok(
46+
!fs.existsSync(lockPath),
47+
"lock file should be removed after updateState completes"
48+
);
49+
});
50+
51+
it("removes lock file even when mutator throws", () => {
52+
try {
53+
updateState(workspace, () => {
54+
throw new Error("mutator explosion");
55+
});
56+
} catch {}
57+
58+
const root = stateRoot(workspace);
59+
const lockPath = path.join(root, "state.json.lock");
60+
assert.ok(
61+
!fs.existsSync(lockPath),
62+
"lock file should be cleaned up after mutator error"
63+
);
64+
});
65+
66+
it("cleans up stale lock files older than 30 seconds", () => {
67+
const root = stateRoot(workspace);
68+
const lockPath = path.join(root, "state.json.lock");
69+
fs.mkdirSync(root, { recursive: true });
70+
71+
fs.writeFileSync(lockPath, "stale\n");
72+
const staleTime = new Date(Date.now() - 60_000);
73+
fs.utimesSync(lockPath, staleTime, staleTime);
74+
75+
updateState(workspace, (state) => {
76+
state.config.staleRecovery = true;
77+
});
78+
79+
const loaded = loadState(workspace);
80+
assert.equal(loaded.config.staleRecovery, true);
81+
assert.ok(!fs.existsSync(lockPath), "stale lock should have been removed");
82+
});
83+
84+
it("concurrent processes do not lose each other's writes", async () => {
85+
const scriptDir = fs.mkdtempSync(path.join(os.tmpdir(), "concurrent-test-"));
86+
const script = path.join(scriptDir, "writer.mjs");
87+
88+
const dataDir = tmpDir;
89+
90+
fs.writeFileSync(
91+
script,
92+
`import { upsertJob } from "${stateModulePath}";\n` +
93+
`import fs from "node:fs";\n` +
94+
`process.env.CLAUDE_PLUGIN_DATA = "${dataDir}";\n` +
95+
`process.env.OPENCODE_COMPANION_SESSION_ID = "child-session";\n` +
96+
`const workspace = "${workspace}";\n` +
97+
`const marker = "${script}.ready";\n` +
98+
`const goSignal = "${script}.go";\n` +
99+
`const doneSignal = "${script}.done";\n` +
100+
`fs.writeFileSync(marker, "ready");\n` +
101+
`while (!fs.existsSync(goSignal)) await new Promise(r => setTimeout(r, 20));\n` +
102+
`upsertJob(workspace, { id: "child-job", status: "running", type: "task" });\n` +
103+
`fs.writeFileSync(doneSignal, "done");\n`
104+
);
105+
106+
try {
107+
const child = fork(script, [], { stdio: "pipe" });
108+
109+
const readyMarker = `${script}.ready`;
110+
const goMarker = `${script}.go`;
111+
const doneMarker = `${script}.done`;
112+
113+
const readyDeadline = Date.now() + 10_000;
114+
while (!fs.existsSync(readyMarker) && Date.now() < readyDeadline) {
115+
await new Promise((r) => setTimeout(r, 50));
116+
}
117+
assert.ok(fs.existsSync(readyMarker), "child did not signal ready in time");
118+
119+
fs.writeFileSync(goMarker, "go");
120+
121+
const doneDeadline = Date.now() + 10_000;
122+
while (!fs.existsSync(doneMarker) && Date.now() < doneDeadline) {
123+
await new Promise((r) => setTimeout(r, 50));
124+
}
125+
assert.ok(fs.existsSync(doneMarker), "child did not finish in time");
126+
127+
await new Promise((resolve) => {
128+
child.on("exit", resolve);
129+
setTimeout(() => { child.kill(); resolve(); }, 5_000);
130+
});
131+
132+
upsertJob(workspace, { id: "parent-job", status: "completed", type: "review" });
133+
134+
const state = loadState(workspace);
135+
const childJob = state.jobs.find((j) => j.id === "child-job");
136+
const parentJob = state.jobs.find((j) => j.id === "parent-job");
137+
138+
assert.ok(childJob, "child job was lost — concurrent write race");
139+
assert.ok(parentJob, "parent job was lost — concurrent write race");
140+
assert.equal(childJob.status, "running");
141+
assert.equal(parentJob.status, "completed");
142+
} finally {
143+
try { fs.rmSync(scriptDir, { recursive: true, force: true }); } catch {}
144+
for (const ext of [".ready", ".go", ".done"]) {
145+
try { fs.rmSync(`${script}${ext}`, { force: true }); } catch {}
146+
}
147+
}
148+
});
149+
});

0 commit comments

Comments
 (0)