diff --git a/server/__tests__/named-lock.test.js b/server/__tests__/named-lock.test.js new file mode 100644 index 0000000..18b73d1 --- /dev/null +++ b/server/__tests__/named-lock.test.js @@ -0,0 +1,116 @@ +/** + * @file Tests for server/lib/named-lock.js: cross-lane named locks — mkdir + * atomicity, the LOCK_MAX_HOLD staleness floor, holder-checked release, and + * status/listing. + * @author Nguyễn Ngọc Trí Vĩ + */ + +const os = require("node:os"); +const path = require("node:path"); +const fs = require("node:fs"); +const { describe, it, after, beforeEach } = require("node:test"); +const assert = require("node:assert/strict"); + +const SUITE_ROOT = fs.mkdtempSync(path.join(os.tmpdir(), "ccam-named-lock-")); +process.env.LANES_ROOT = SUITE_ROOT; +after(() => fs.rmSync(SUITE_ROOT, { recursive: true, force: true })); + +const namedLock = require("../lib/named-lock"); + +beforeEach(() => { + fs.rmSync(namedLock.locksRoot(), { recursive: true, force: true }); + delete process.env.LOCK_MAX_HOLD; +}); + +describe("tryAcquire / release", () => { + it("acquires a free lock and reports it held afterward", () => { + const result = namedLock.tryAcquire("build", "lane1"); + assert.deepEqual(result, { acquired: true }); + const status = namedLock.status("build"); + assert.equal(status.held, true); + assert.equal(status.holder, "lane1"); + }); + + it("a second acquire on the same name reports not-acquired with the current holder", () => { + namedLock.tryAcquire("build", "lane1"); + const second = namedLock.tryAcquire("build", "lane2"); + assert.equal(second.acquired, false); + assert.equal(second.holder, "lane1"); + }); + + it("a second acquire succeeds after release", () => { + namedLock.tryAcquire("build", "lane1"); + namedLock.release("build", "lane1"); + const second = namedLock.tryAcquire("build", "lane2"); + assert.equal(second.acquired, true); + assert.equal(namedLock.status("build").holder, "lane2"); + }); + + it("release from a non-holder is refused and leaves the lock held", () => { + namedLock.tryAcquire("build", "lane1"); + assert.throws( + () => namedLock.release("build", "lane2"), + (err) => err.code === "ENOTHOLDER" + ); + assert.equal(namedLock.status("build").held, true); + assert.equal(namedLock.status("build").holder, "lane1"); + }); + + it("releasing a lock that doesn't exist throws ENOLOCK", () => { + assert.throws( + () => namedLock.release("never-held", "lane1"), + (err) => err.code === "ENOLOCK" + ); + }); +}); + +describe("staleness with a floor", () => { + /** Back-date a lock's owner file by writing it directly, bypassing tryAcquire's "now". */ + function backdate(name, holder, ageSec) { + const dir = path.join(namedLock.locksRoot(), name); + fs.mkdirSync(dir, { recursive: true }); + const since = Math.floor(Date.now() / 1000) - ageSec; + fs.writeFileSync(path.join(dir, "owner"), `${holder} ${since}`); + } + + it("a holder older than LOCK_MAX_HOLD is broken on the next acquire", () => { + backdate("stale", "lane1", 2701); // just past the 2700s default + const result = namedLock.tryAcquire("stale", "lane2"); + assert.equal(result.acquired, true); + assert.equal(namedLock.status("stale").holder, "lane2"); + }); + + it("a holder backdated within the 300s floor is NOT broken, even with LOCK_MAX_HOLD=1", () => { + process.env.LOCK_MAX_HOLD = "1"; + backdate("floor-test", "lane1", 100); // within the 300s floor + const result = namedLock.tryAcquire("floor-test", "lane2"); + assert.equal(result.acquired, false); + assert.equal(result.holder, "lane1"); + }); + + it("a holder older than a LOCK_MAX_HOLD set above the floor is broken", () => { + process.env.LOCK_MAX_HOLD = "400"; + backdate("above-floor", "lane1", 401); + const result = namedLock.tryAcquire("above-floor", "lane2"); + assert.equal(result.acquired, true); + }); +}); + +describe("listLocks", () => { + it("lists every currently-held lock", () => { + namedLock.tryAcquire("build", "lane1"); + namedLock.tryAcquire("e2e", "lane2"); + const locks = namedLock.listLocks().sort((a, b) => a.name.localeCompare(b.name)); + assert.deepEqual( + locks.map((l) => [l.name, l.holder]), + [ + ["build", "lane1"], + ["e2e", "lane2"], + ] + ); + }); + + it("returns an empty array when no locks exist", () => { + assert.deepEqual(namedLock.listLocks(), []); + }); +}); diff --git a/server/lib/named-lock.js b/server/lib/named-lock.js new file mode 100644 index 0000000..a73e069 --- /dev/null +++ b/server/lib/named-lock.js @@ -0,0 +1,144 @@ +/** + * @file Cross-lane named locks: serialize a machine-thrashing step (a build, + * an e2e run) across ALL lanes, as opposed to `lane-lock.js`'s per-lane, + * in-process serialization (a different axis — a separate module on purpose, + * so the two are never conflated). + * + * `mkdir` is the atomicity primitive: it throws `EEXIST` when the directory + * already exists, so "is it free" and "claim it" are one syscall, never a + * check-then-create race. No `flock` dependency, unlike Shipyard's original + * (`brew install flock` on macOS). + * @author Nguyễn Ngọc Trí Vĩ + */ + +const fs = require("node:fs"); +const path = require("node:path"); + +const { LANES_ROOT } = require("./worktree"); + +/** + * However low `LOCK_MAX_HOLD` is set, a holder younger than this can never be + * broken. This is what stops an impatient env-var edit from force-breaking a + * genuinely live holder — the floor is the actual safety property, not the + * configurable default. + */ +const LOCK_MAX_HOLD_FLOOR_SEC = 300; + +/** Where every named lock's directory lives. */ +function locksRoot() { + return path.join(LANES_ROOT, ".locks"); +} + +/** `Math.max(LOCK_MAX_HOLD env, the 300s floor)`, read per call so a test (or an + * operator) can change it without a restart. */ +function effectiveMaxHoldSec() { + const raw = Number(process.env.LOCK_MAX_HOLD); + const configured = Number.isFinite(raw) && raw > 0 ? raw : 2700; + return Math.max(configured, LOCK_MAX_HOLD_FLOOR_SEC); +} + +function ownerPath(name) { + return path.join(locksRoot(), name, "owner"); +} + +/** Parse an owner file's `" "` contents. */ +function readOwner(name) { + let text; + try { + text = fs.readFileSync(ownerPath(name), "utf8"); + } catch { + return null; + } + const match = /^(\S+) (\d+)$/.exec(text.trim()); + if (!match) return null; + const since = Number(match[2]); + return { holder: match[1], since, ageSec: Math.floor(Date.now() / 1000) - since }; +} + +/** + * Try to acquire a named lock once. Never blocks, never retries — the caller + * (the CLI) owns the polling loop; CCAM's server-side primitives are always + * single-shot. + * + * A stale holder (older than `effectiveMaxHoldSec()`) is broken automatically: + * its lock directory is removed and the acquire is retried once before + * answering. + * + * @param {string} name - Lock name. + * @param {string} holder - Identity to record as the owner (e.g. `"lane3"`). + * @returns {{acquired: true} | {acquired: false, holder: string, since: number, ageSec: number}} + */ +function tryAcquire(name, holder) { + const dir = path.join(locksRoot(), name); + fs.mkdirSync(locksRoot(), { recursive: true }); + + try { + fs.mkdirSync(dir); + } catch (err) { + if (err.code !== "EEXIST") throw err; + const owner = readOwner(name); + if (!owner || owner.ageSec <= effectiveMaxHoldSec()) { + return owner + ? { acquired: false, holder: owner.holder, since: owner.since, ageSec: owner.ageSec } + : { acquired: false, holder: "unknown", since: 0, ageSec: Infinity }; + } + // Stale — break it and retry once. + fs.rmSync(dir, { recursive: true, force: true }); + fs.mkdirSync(dir); + } + + fs.writeFileSync(path.join(dir, "owner"), `${holder} ${Math.floor(Date.now() / 1000)}`); + return { acquired: true }; +} + +/** + * Release a lock. Refuses (throws `ENOTHOLDER`) when `holder` does not match + * the recorded owner — a release never trusts its caller, the same rule every + * other destructive path in this project follows. + * + * @param {string} name - Lock name. + * @param {string} holder - Must match the current owner. + */ +function release(name, holder) { + const owner = readOwner(name); + if (!owner) { + throw Object.assign(new Error(`no such lock: ${name}`), { code: "ENOLOCK" }); + } + if (owner.holder !== holder) { + throw Object.assign(new Error(`lock "${name}" is held by ${owner.holder}, not ${holder}`), { + code: "ENOTHOLDER", + currentHolder: owner.holder, + }); + } + fs.rmSync(path.join(locksRoot(), name), { recursive: true, force: true }); +} + +/** Current state of one named lock, read-only. */ +function status(name) { + const owner = readOwner(name); + return owner ? { held: true, ...owner } : { held: false }; +} + +/** Every currently-held lock. */ +function listLocks() { + let entries = []; + try { + entries = fs.readdirSync(locksRoot()); + } catch { + return []; + } + return entries + .map((name) => ({ name, ...status(name) })) + .filter((lock) => lock.held) + .map(({ held, ...rest }) => rest); +} + +module.exports = { + LOCK_MAX_HOLD_FLOOR_SEC, + locksRoot, + effectiveMaxHoldSec, + tryAcquire, + release, + status, + listLocks, +};