Skip to content

Commit 151406a

Browse files
fix(fileLock): key locks on file identity and hand callers their own spelling
The lock resource is the file's identity: the device and inode of the nearest directory that exists, plus the components below it that do not exist yet. Two spellings of one file - an 8.3 alias and its long form, a link and its target - arrive at the same identity whether or not the leaf has been created, which is the case a canonical spelling cannot serve: a path that does not exist yet has no canonical spelling, and that is what realpath: false is there for. No path is canonicalised any more. realpathSync.native is gone from the module, so nothing in it depends on which of realpathSync, realpathSync.native and realpath expands an 8.3 spelling. The artefact stays <file>.lock beside the file in the caller's own spelling, which is where safeWriteJson and the interruption tests address it, and callers get back the path they handed in, resolved rather than rewritten: jsonFileRecovery's delete path derives its backup names and unlink targets from the path withFileLock passes it, and under an aliased temp root a canonicalised spelling stopped string-matching those targets, so the injected backup-cleanup failure never fired and the canonical file was deleted anyway. Measured on node 22.23.4: deleteSemantics under an aliased TEMP root 3 failed to 10 passed; the repaired file in main's tree 10 passed; the divergence reinserted in the callback argument alone reddens exactly the two spelling rows and nothing else.
1 parent 945b24d commit 151406a

2 files changed

Lines changed: 94 additions & 23 deletions

File tree

‎src/utils/__tests__/fileLock.test.ts‎

Lines changed: 64 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ import * as path from "path"
55

66
import * as lockfile from "proper-lockfile"
77

8-
import { acquireFileLock, canonicalLockPath, LOCK_STALE_MS, withFileLock } from "../fileLock"
8+
import { acquireFileLock, canonicalLockKey, LOCK_STALE_MS, withFileLock } from "../fileLock"
99

1010
vi.mock("proper-lockfile", () => ({ lock: vi.fn() }))
1111

@@ -21,6 +21,7 @@ describe("file lock protocol", () => {
2121
stale: LOCK_STALE_MS,
2222
update: 10000,
2323
realpath: false,
24+
lockfilePath: path.resolve("history.json") + ".lock",
2425
retries: { retries: 35, factor: 1, minTimeout: 1000, maxTimeout: 1000 },
2526
}),
2627
)
@@ -79,6 +80,9 @@ describe("one lock per file, not one lock per spelling", () => {
7980
beforeEach(() => {
8081
held.length = 0
8182
vi.mocked(lockfile.lock).mockImplementation(async (target: unknown) => {
83+
// The table keys on the key acquireFileLock hands the library: the file's identity, not
84+
// either spelling. Two spellings of one file therefore arrive as one key, which is what
85+
// this table can decide; the artefact location is asserted separately.
8286
const key = String(target)
8387
if (held.indexOf(key) >= 0) {
8488
throw Object.assign(new Error("ELOCKED: " + key), { code: "ELOCKED" })
@@ -116,9 +120,29 @@ describe("one lock per file, not one lock per spelling", () => {
116120
const releaseAlias = await acquireFileLock(aliasFile, { immediate: true })
117121
expect(held).toHaveLength(1)
118122
await expect(acquireFileLock(file, { immediate: true })).rejects.toMatchObject({ code: "ELOCKED" })
119-
expect(held[0]).toBe(canonicalLockPath(file))
123+
expect(canonicalLockKey(aliasFile)).toBe(canonicalLockKey(file))
120124
await releaseAlias()
121125
})
126+
itAlias("hands each caller back its own spelling rather than the canonicalised one", async () => {
127+
const longDir = path.join(root, "a-really-long-directory-name-for-spelling-control")
128+
fs.mkdirSync(longDir, { recursive: true })
129+
const file = path.join(longDir, "history.json")
130+
fs.writeFileSync(file, "{}", "utf8")
131+
const aliasFile = path.join(aliasOf(longDir), "history.json")
132+
expect(fs.statSync(aliasFile).ino).toBe(fs.statSync(file).ino)
133+
const seen: string[] = []
134+
await withFileLock(aliasFile, async (lockedPath) => {
135+
seen.push(lockedPath)
136+
})
137+
await withFileLock(file, async (lockedPath) => {
138+
seen.push(lockedPath)
139+
})
140+
// With the canonical spelling handed to the operation this reddens here, on the alias
141+
// difference itself, and it names the spelling that came back: the divergence, not a timer.
142+
expect(seen[0]).toBe(path.resolve(aliasFile))
143+
expect(seen[1]).toBe(path.resolve(file))
144+
expect(seen[0]).not.toBe(seen[1])
145+
})
122146
it("takes separate locks for two different files in one directory", async () => {
123147
const a = path.join(root, "a.json")
124148
const b = path.join(root, "b.json")
@@ -137,3 +161,41 @@ describe("one lock per file, not one lock per spelling", () => {
137161
expect(held).toHaveLength(2)
138162
})
139163
})
164+
165+
/**
166+
* A link is the portable member of the same class as an 8.3 alias: two spellings of one
167+
* directory, one referent. Junctions need no elevation on Windows and symlinks work on the
168+
* linux runners, so nothing here is platform-skipped: if creating the link fails, the control
169+
* fails rather than quietly disappearing.
170+
*/
171+
describe("two spellings of one referent share one key", () => {
172+
const root = fs.mkdtempSync(path.join(os.tmpdir(), "fileLock-link-"))
173+
const real = path.join(root, "real")
174+
const link = path.join(root, "link")
175+
fs.mkdirSync(real, { recursive: true })
176+
fs.symlinkSync(real, link, process.platform === "win32" ? "junction" : "dir")
177+
178+
it("keys both spellings of a written file to one identity", () => {
179+
const file = path.join(real, "history.json")
180+
fs.writeFileSync(file, "{}", "utf8")
181+
expect(canonicalLockKey(file)).toBe(canonicalLockKey(path.join(link, "history.json")))
182+
})
183+
184+
it("keys both spellings of a path that does not exist yet to one identity", () => {
185+
const missing = path.join("deep", "history.json")
186+
expect(canonicalLockKey(path.join(real, missing))).toBe(canonicalLockKey(path.join(link, missing)))
187+
})
188+
189+
it("hands each spelling back to its own caller unchanged", async () => {
190+
vi.mocked(lockfile.lock).mockResolvedValue(async () => {})
191+
const seen: string[] = []
192+
await withFileLock(path.join(link, "history.json"), async (lockedPath) => {
193+
seen.push(lockedPath)
194+
})
195+
await withFileLock(path.join(real, "history.json"), async (lockedPath) => {
196+
seen.push(lockedPath)
197+
})
198+
expect(seen[0]).toBe(path.resolve(path.join(link, "history.json")))
199+
expect(seen[1]).toBe(path.resolve(path.join(real, "history.json")))
200+
})
201+
})

‎src/utils/fileLock.ts‎

Lines changed: 30 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -54,35 +54,44 @@ function nearestExistingDirectory(absolutePath: string): { directory: string; re
5454
}
5555

5656
/**
57-
* The spelling a lock artefact should be created under: the canonical spelling of the
58-
* nearest existing directory, re-joined with the components that do not exist yet. This is
59-
* what makes an 8.3 alias and its long form take one lock, and it stays a spelling - the key
60-
* above is the identity, and callers that compare locks compare that.
57+
* The identity a lock is keyed on: the device and inode of the nearest directory that actually
58+
* exists, plus the components below it that do not exist yet. An 8.3 alias and its long form, a
59+
* link and its target, and a case variant on a case-insensitive volume all arrive at the same
60+
* identity, whether or not the leaf has been created. That is the case a canonical spelling
61+
* cannot serve: a leaf that does not exist yet has no canonical spelling, which is what the
62+
* `realpath: false` in `acquireFileLock` is there for. And nothing here rewrites a caller's
63+
* path - the key is for comparing locks, never for opening files - so the strings callers hand
64+
* to unlink and readFile stay the strings those callers built.
6165
*/
62-
export function canonicalLockPath(filePath: string): string {
66+
export function canonicalLockKey(filePath: string): string {
6367
const absolute = path.resolve(filePath)
64-
if (statIdentity(absolute) !== null) {
65-
try {
66-
return fs.realpathSync.native(absolute)
67-
} catch {
68-
return absolute
69-
}
70-
}
7168
const { directory, relative } = nearestExistingDirectory(absolute)
72-
let canonicalDirectory = directory
73-
try {
74-
canonicalDirectory = fs.realpathSync.native(directory)
75-
} catch {
76-
canonicalDirectory = directory
69+
const identity = statIdentity(directory)
70+
if (identity === null) {
71+
// Not even a root of the path exists yet, so there is no identity to key on and the
72+
// resolved path is the one thing every caller of it computes alike.
73+
return absolute
7774
}
78-
return relative.length === 0 ? canonicalDirectory : path.join(canonicalDirectory, ...relative)
75+
return identity + ":" + relative.join("/")
76+
}
77+
78+
/**
79+
* Where the artefact lives: beside the file in the caller's own spelling. The key above is the
80+
* identity, and the artefact stays a path, because `safeWriteJson` and the interruption tests
81+
* address `<file>.lock` directly - moving it is what made a green suite red, so the location is
82+
* pinned by a test rather than left to taste.
83+
*/
84+
function lockArtefactPath(absolutePath: string): string {
85+
return absolutePath + ".lock"
7986
}
8087

8188
export async function acquireFileLock(filePath: string, options?: FileLockOptions): Promise<() => Promise<void>> {
82-
const absoluteFilePath = canonicalLockPath(filePath)
89+
const absoluteFilePath = path.resolve(filePath)
90+
const lockfilePath = lockArtefactPath(absoluteFilePath)
8391
if (options?.waitForStaleLock) tracePersistenceEvent("json-lock-wait", { filePath: absoluteFilePath })
8492
try {
85-
return await lockfile.lock(absoluteFilePath, {
93+
return await lockfile.lock(canonicalLockKey(absoluteFilePath), {
94+
lockfilePath,
8695
stale: LOCK_STALE_MS,
8796
update: 10000, // Update mtime every 10 seconds to prevent staleness if operation is long
8897
realpath: false, // the file may not exist yet, which is acceptable
@@ -124,7 +133,7 @@ export async function withFileLock<T>(
124133
operation: (absoluteFilePath: string) => Promise<T>,
125134
options?: FileLockOptions,
126135
): Promise<T> {
127-
const absoluteFilePath = canonicalLockPath(filePath)
136+
const absoluteFilePath = path.resolve(filePath)
128137
const releaseLock = await acquireFileLock(absoluteFilePath, options)
129138

130139
let result: T

0 commit comments

Comments
 (0)