feat(locks): add cross-lane named locks (mkdir-atomic, staleness floor) (D)
This commit is contained in:
@@ -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ĩ <vinnt@smartgift.vn>
|
||||
*/
|
||||
|
||||
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(), []);
|
||||
});
|
||||
});
|
||||
@@ -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ĩ <vinnt@smartgift.vn>
|
||||
*/
|
||||
|
||||
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 `"<holder> <epochSeconds>"` 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,
|
||||
};
|
||||
Reference in New Issue
Block a user