Skip to content

Commit 7169173

Browse files
fix(file-safety): stop the lock-key walk at the file it lands on, and always stage a named token
resolveLockKey propagated a resolution error only out of the first canonicalisation: a relative referent whose link parent answered EACCES was joined onto the spelled parent, keying this writer where no writer that reached the referent keys - two locks for one file. Only a parent that is not there (ENOENT) may fall back to that join now. The bounded walk also rejected a chain that landed on the file exactly at its bound, so a peer that renames the referent away mid-EPERM-fallback made the write fail where waiting for it would have committed. The bound now checks the terminal path once and still rejects a ninth link; the cycle row's read count moves from 8 to 9 because the ninth read is the terminal check that bounds it. createStagingFilePath and createBackupFilePath took their token from Math.random().toString(36).substring(2), which answers the empty string when Math.random() answers 0 (measured with node 22.23.4): the name ended `_<timestamp>_.tmp`, the one tail jsonFileRecovery cannot collect on the underscore-anchored prefix, where the token is the only thing that attributes the name to this target. Both writers guarantee a non-empty token now, and the dot-anchored pattern still accepts a token-less tail because a leftover written before the guarantee is not distinguishable from one written after it. safeWriteText.alias.spec.ts gated every alias row on its own capability probe, so a cmd command that quoted the directory badly answered null for the probe and skipped the file instead of failing it; one row now asks cmd about its own directory. CodeRabbit threads answered here: 4509550084, 4509550081, 4509550093, 4509550078.
1 parent 4b85be9 commit 7169173

8 files changed

Lines changed: 189 additions & 14 deletions

File tree

‎src/services/file-safety/__tests__/safeWriteText.alias.spec.ts‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -152,6 +152,34 @@ describe("safeWriteText staging guard against a second spelling of the target di
152152
},
153153
)
154154

155+
// The probe above is the harness for every row in this file, so a command that quotes the directory
156+
// badly answers null for the probe directory and it.runIf skips the whole file: the suite cannot tell
157+
// "this volume generates no 8.3 names" from "our cmd command broke". This row asks its own question,
158+
// about its own directory, and skips only on the platform that has no cmd.exe to ask.
159+
it.runIf(IS_WINDOWS)("checks alias discovery without going through the capability flag", () => {
160+
const spacedDir = path.join(tempDir, "SELF CHECKING TARGET DIRECTORY")
161+
fs.mkdirSync(spacedDir)
162+
// The same command shortPathOf runs, with the answer kept instead of collapsed to null.
163+
const query = 'for %A in ("' + spacedDir + '") do @echo %~sA'
164+
const raw = spawnSync(SHORT_NAME_PROBE_BIN, ["/c", query], {
165+
encoding: "utf8",
166+
windowsVerbatimArguments: true,
167+
})
168+
const answers = raw.stdout.trim().split(/\r?\n/)
169+
// One answer, not one answer per word of the directory name.
170+
expect(answers).toHaveLength(1)
171+
expect(fs.existsSync(answers[0])).toBe(true)
172+
expect(fs.statSync(answers[0]).isDirectory()).toBe(true)
173+
// Where this volume really does hand out an alias - the answer carries the short-name marker - the
174+
// production probe has to answer it for the same directory. A command that lost its quotes answers
175+
// one line per word here and fails this row, where the flag above would only have skipped it.
176+
if (answers[0].includes(SHORT_NAME_MARKER)) {
177+
const short = shortPathOf(spacedDir)
178+
expect(short).not.toBeNull()
179+
expect(short).toBe(answers[0])
180+
}
181+
})
182+
155183
// The probe is the harness for both rows below, and its own answer is what breaks when the
156184
// directory is quoted badly: a space in a directory name is not exotic on Windows - every
157185
// profile path under "Documents and Settings" has one - and an unquoted for-set turns one

‎src/services/file-safety/__tests__/safeWriteText.spec.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1621,7 +1621,10 @@ describe("resolveLockKey", () => {
16211621
vi.mocked(fs.readlink).mockImplementation(async () => "a.json")
16221622

16231623
await expect(resolveLockKey("/tmp/linkdir/a.json")).rejects.toThrow("the symlink chain is deeper than 8 links")
1624-
expect(fs.readlink).toHaveBeenCalledTimes(8)
1624+
// Eight reads advance the walk and the ninth is the terminal check that finds the link past the
1625+
// bound. A cycle still stops on this count; it is the count that bounds the walk, not the count
1626+
// it used before the walk could tell a chain ending at the bound from one running past it.
1627+
expect(fs.readlink).toHaveBeenCalledTimes(9)
16251628
})
16261629

16271630
it("propagates a readlink failure that is not a not-a-link or absent answer", async () => {

‎src/services/file-safety/safeWriteText.ts‎

Lines changed: 20 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -342,28 +342,39 @@ export async function resolveLockKey(absoluteFilePath: string): Promise<string>
342342
// loss this function exists to prevent, and guessing it is how that loss arrives.
343343
const linkWalkLimit = 8
344344
let key = absoluteFilePath
345-
for (let depth = 0; depth < linkWalkLimit; depth++) {
345+
// No condition: the bound check inside the loop is what ends the walk, and an exit-never loop is
346+
// what keeps this function from needing an unreachable return after it.
347+
for (let depth = 0; ; depth++) {
346348
const target = await fs.readlink(key).catch((linkError: unknown) => {
347349
const code = errorCode(linkError)
348350
if (code === "ENOENT" || code === "EINVAL") return undefined
349351
throw linkError
350352
})
351353
if (target === undefined) return await canonicalDirKey(key)
354+
// At the bound the walk has followed linkWalkLimit links and `key` is what the last of them names.
355+
// A link there is one link past what this bound can name, so it rejects; a non-link there is the
356+
// file the chain ends on, and that is a key even when the chain arrived at it exactly at the bound.
357+
if (depth === linkWalkLimit) {
358+
throw new Error(
359+
`safeWriteText: could not resolve a lock key for ${absoluteFilePath}: the symlink chain is deeper than ${linkWalkLimit} links`,
360+
)
361+
}
352362
// A relative referent is relative to the link's REAL parent, not to the spelling the
353363
// caller arrived with: under a symlinked directory `..` names the referent's parent,
354364
// so a lexical join keys a different file and the writer through the alias stops
355-
// excluding the writer through the referent. When the link's own parent cannot be
356-
// canonicalized - a dangling chain - the lexical join is the only answer available.
365+
// excluding the writer through the referent. Only a parent that is not there at all - ENOENT, the
366+
// dangling chain - may fall back to that join, because there the join is the only answer
367+
// available. EACCES or EIO says nothing about where this link lives, and joining onto the spelled
368+
// parent keys this writer where no writer that reached the referent keys: the two locks for one
369+
// file that this walk exists to prevent.
357370
const referentParent = path.isAbsolute(target)
358371
? undefined
359-
: await fs.realpath(path.dirname(key)).catch(() => undefined)
372+
: await fs.realpath(path.dirname(key)).catch((parentError: unknown) => {
373+
if (errorCode(parentError) !== "ENOENT") throw parentError
374+
return undefined
375+
})
360376
key = await canonicalDirKey(path.resolve(referentParent ?? path.dirname(key), target))
361377
}
362-
// The bound only exists to terminate a cycle. Past it the chain names no file, so
363-
// the caller is told instead of handed whichever link the walk stopped on.
364-
throw new Error(
365-
`safeWriteText: could not resolve a lock key for ${absoluteFilePath}: the symlink chain is deeper than ${linkWalkLimit} links`,
366-
)
367378
}
368379
}
369380

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

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -152,6 +152,29 @@ describe("replacement leftover name patterns", () => {
152152
// The other half of the same rule: on the underscore-anchored staged prefix the token is the only
153153
// thing that attributes a staged-looking name to this target, so the very same tail shape there
154154
// is somebody else's in-flight file and must survive.
155+
// The token a writer can actually be handed: Math.random() === 0 stringifies to "0", so
156+
// substring(2) answers the empty string and the name ends timestamp-underscore-dot-tmp (measured
157+
// with node 22.23.4). Under the dot-anchored prefix that name is still this target's own leftover -
158+
// the literal dot already pins the basename - so recovery has to take it.
159+
it("collects a dot-anchored backup whose random token came out empty", async () => {
160+
const leftover = path.join(dir, ".a.json.bak_1730000000000_.tmp")
161+
await fs.writeFile(leftover, "stale")
162+
await expect(recoverMissingJsonFile(target)).resolves.toBe(true)
163+
expect(JSON.parse(await fs.readFile(target, "utf8"))).toEqual({ committed: true })
164+
await expect(fs.access(leftover)).rejects.toMatchObject({ code: "ENOENT" })
165+
})
166+
167+
// And the name the writer produces out of that same answer: safeWriteJson guarantees a token, so the
168+
// staged name carries the empty token's stand-in, and the staged prefix - where the token is the only
169+
// thing that attributes the name - still recognises it.
170+
it("collects a staged leftover whose token is the empty-token stand-in", async () => {
171+
const leftover = path.join(dir, ".new_a.json_1730000000000_0.tmp")
172+
await fs.writeFile(leftover, "stale")
173+
await expect(recoverMissingJsonFile(target)).resolves.toBe(true)
174+
expect(JSON.parse(await fs.readFile(target, "utf8"))).toEqual({ committed: true })
175+
await expect(fs.access(leftover)).rejects.toMatchObject({ code: "ENOENT" })
176+
})
177+
155178
it("does not collect a staged-looking name that lacks the token", async () => {
156179
const unscoped = path.join(dir, ".new_a.json_1.tmp")
157180
await fs.writeFile(unscoped, "someone else's staging file")

‎src/utils/__tests__/safeWriteJson.lockKey.spec.ts‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -194,6 +194,85 @@ describe("safeWriteJson lock key under a peer commit", () => {
194194
await expect(resolveLockKey(file)).rejects.toBe(eacces)
195195
})
196196

197+
it("propagates a parent-directory error instead of joining the referent onto the spelled parent", async () => {
198+
// The link's parent is itself a directory link and its realpath answers EACCES while the referent
199+
// is relative and dangling. Joining the referent onto the spelled parent names dir/aliasdir/other
200+
// - a key no writer that reached the referent uses - and those two writers then hold two locks for
201+
// one file. Only ENOENT, the chain simply not being there, may fall back to that join.
202+
const dir = await makeDir("lockkey-")
203+
const spelledParent = path.join(dir, "aliasdir", "notes")
204+
const link = path.join(spelledParent, "link.json")
205+
currentLink = link
206+
const referent = "../other/x.json"
207+
const eacces = Object.assign(new Error("EACCES: permission denied"), { code: "EACCES" })
208+
mockedRealpath.mockImplementation(async (target) => {
209+
const p = String(target)
210+
if (p === link) {
211+
throw enoent // peer mid-commit: the referent is renamed away from this name
212+
}
213+
if (p === spelledParent) {
214+
throw eacces // this directory link cannot be canonicalized right now
215+
}
216+
return p
217+
})
218+
mockedLstat.mockImplementation(async (target) => symlinkStat(target))
219+
mockedReadlink.mockImplementation(async (target) =>
220+
String(target) === link ? referent : Promise.reject(enoent),
221+
)
222+
223+
await expect(resolveLockKey(link)).rejects.toBe(eacces)
224+
})
225+
226+
it("keys the file a chain lands on exactly at its bound", async () => {
227+
// A peer that pulls the referent away mid-EPERM-fallback can leave this writer walking a chain
228+
// it only finishes at the bound. Eight links land on the file, and the bound has to name that
229+
// file - not whichever link the walk happened to stop on - or the write fails where waiting for
230+
// the peer would have committed.
231+
const dir = await makeDir("lockkey-")
232+
const spelling = (n: number) => path.join(dir, "l" + n + ".json")
233+
currentLink = spelling(0)
234+
const hops = new Map<string, string>()
235+
for (let n = 0; n < 8; n++) {
236+
hops.set(spelling(n), spelling(n + 1))
237+
}
238+
const einval = Object.assign(new Error("EINVAL: invalid argument"), { code: "EINVAL" })
239+
mockedRealpath.mockImplementation(async (target) =>
240+
String(target) === currentLink ? Promise.reject(enoent) : String(target),
241+
)
242+
mockedLstat.mockImplementation(async (target) => symlinkStat(target))
243+
mockedReadlink.mockImplementation(async (target) => {
244+
const hop = hops.get(String(target))
245+
// l8 is a regular file: a real readlink answers EINVAL for it (measured with node 22.23.4
246+
// on win32), which is the answer that ends the walk.
247+
return hop === undefined ? Promise.reject(einval) : hop
248+
})
249+
250+
expect(await resolveLockKey(spelling(0))).toBe(spelling(8))
251+
})
252+
253+
it("rejects a chain that runs past its bound instead of naming whichever link it stopped on", async () => {
254+
// The other side of the same bound: nine links name no file this writer can lock, and the
255+
// caller has to be told rather than handed l8, which two writers entering the chain from
256+
// opposite ends would not both name.
257+
const dir = await makeDir("lockkey-")
258+
const spelling = (n: number) => path.join(dir, "l" + n + ".json")
259+
currentLink = spelling(0)
260+
const hops = new Map<string, string>()
261+
for (let n = 0; n < 9; n++) {
262+
hops.set(spelling(n), spelling(n + 1))
263+
}
264+
mockedRealpath.mockImplementation(async (target) =>
265+
String(target) === currentLink ? Promise.reject(enoent) : String(target),
266+
)
267+
mockedLstat.mockImplementation(async (target) => symlinkStat(target))
268+
mockedReadlink.mockImplementation(async (target) => {
269+
const hop = hops.get(String(target))
270+
return hop === undefined ? Promise.reject(new Error("readlink answered no code")) : hop
271+
})
272+
273+
await expect(resolveLockKey(spelling(0))).rejects.toThrow(/deeper than 8 links/)
274+
})
275+
197276
it("keys a relative referent through the link's real parent, not the spelled one", async () => {
198277
// The link lives under a directory that is itself a link and its referent is relative.
199278
// `..` names the referent's parent, so joining the referent onto the spelling the caller

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

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -962,6 +962,34 @@ describe("safeWriteJson", () => {
962962

963963
// ── post-commit durability: the published target must survive (PI regression) ──
964964

965+
it("stages under a token that a zero random still fills", async () => {
966+
// Math.random() === 0 stringifies to "0", so substring(2) answers the empty string and the staging
967+
// name would end <timestamp>_.tmp (measured with node 22.23.4) - the one tail jsonFileRecovery
968+
// cannot collect on the underscore-anchored prefix, where the token is the only thing that
969+
// attributes the name to this target. The other half of the guarantee: a non-zero random still has
970+
// to produce its own token rather than a constant.
971+
const dir = await fs.mkdtemp(path.join(os.tmpdir(), "safe-write-json-token-"))
972+
const stagedName = async (name: string): Promise<string> => {
973+
const file = path.join(dir, name)
974+
await safeWriteJson(file, { committed: true })
975+
const calls = vi.mocked(fs.rename).mock.calls
976+
// The commit rename is the last rename of the write: its source is the staging file.
977+
return path.basename(String(calls[calls.length - 1][0]))
978+
}
979+
const randomSpy = vi.spyOn(Math, "random").mockReturnValue(0)
980+
const zeroName = await stagedName("zero.json")
981+
randomSpy.mockReturnValue(0.5)
982+
const halfName = await stagedName("half.json")
983+
randomSpy.mockRestore()
984+
await fs.rm(dir, { recursive: true, force: true })
985+
986+
expect(zeroName).toMatch(/^\.new_zero\.json_\d+_[^_]+\.tmp$/)
987+
expect(halfName).toMatch(/^\.new_half\.json_\d+_[0-9a-z]+\.tmp$/)
988+
// "i" is what 0.5 answers in this shape: 0.5.toString(36) is "0.i", so substring(2) is "i"
989+
// (measured with node 22.23.4). The staging name has to carry it, not a constant.
990+
expect(halfName).toContain("_i.tmp")
991+
})
992+
965993
it("keeps the published target with its new content when the post-commit directory fsync fails", async () => {
966994
const fsSyncMod = await import("fs")
967995
const realFsync = fsSyncMod.fsyncSync

‎src/utils/jsonFileRecovery.ts‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,10 @@ function getStagedReplacementPrefix(absoluteFilePath: string): string {
2828
* core/task-persistence/__tests__/TaskHistoryStore.realConcurrency.spec.ts still plants and
2929
* migration must still recover, is a backup of this target. Current writers append
3030
* `_<timestamp>_<random>.tmp` (see safeWriteJson's createStagingFilePath and createBackupFilePath);
31-
* the base36 token never contains an underscore and the timestamp is all digits.
31+
* the base36 token never contains an underscore, and both writers now guarantee it is not empty:
32+
* Math.random() === 0 stringifies to "0", so substring(2) answers the empty string and the tail
33+
* would be `<timestamp>_.tmp` (measured with node 22.23.4). This pattern still accepts that tail,
34+
* because a leftover written before the guarantee is not distinguishable from one written after it.
3235
*
3336
* The underscore-anchored staged prefix `.new_<basename>_` is not scoped by its prefix alone. A
3437
* basename that starts with this basename plus an underscore - `a.json_extra.json` beside `a.json` -
@@ -38,7 +41,7 @@ function getStagedReplacementPrefix(absoluteFilePath: string): string {
3841
* the full `<ts>_<rand>.tmp` tail attributes a staged-looking name, so without the token it is not
3942
* this target's leftover.
4043
*/
41-
const ANCHORED_LEFTOVER_TAIL = /^\d+(_[^_]+)?\.tmp$/
44+
const ANCHORED_LEFTOVER_TAIL = /^\d+(_[^_]*)?\.tmp$/
4245
const STAGED_LEFTOVER_TAIL = /^\d+_[^_]+\.tmp$/
4346

4447
/** Whether `entry` is a leftover this target's own writer staged. */

‎src/utils/safeWriteJson.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -68,14 +68,14 @@ export interface SafeWriteJsonOptions {
6868
function createStagingFilePath(absoluteFilePath: string): string {
6969
return path.join(
7070
path.dirname(absoluteFilePath),
71-
`.new_${path.basename(absoluteFilePath)}_${Date.now()}_${Math.random().toString(36).substring(2)}.tmp`,
71+
`.new_${path.basename(absoluteFilePath)}_${Date.now()}_${Math.random().toString(36).substring(2) || "0"}.tmp`,
7272
)
7373
}
7474

7575
function createBackupFilePath(absoluteFilePath: string): string {
7676
return path.join(
7777
path.dirname(absoluteFilePath),
78-
`.${path.basename(absoluteFilePath)}.bak_${Date.now()}_${Math.random().toString(36).substring(2)}.tmp`,
78+
`.${path.basename(absoluteFilePath)}.bak_${Date.now()}_${Math.random().toString(36).substring(2) || "0"}.tmp`,
7979
)
8080
}
8181

0 commit comments

Comments
 (0)