@@ -192,6 +192,29 @@ async function fixedPublishTarget(absolutePath: string): Promise<string> {
192192 } )
193193}
194194
195+ /**
196+ * How many times a guarded write re-takes its locks when a peer retargets the alias while
197+ * this write holds them. Three acquisitions cover a protocol writer that swaps the link once
198+ * and a second writer that queues behind it; a target that keeps moving is a livelock, and
199+ * the write reports it as a guard rejection instead of looping.
200+ */
201+ const MAX_LOCK_REACQUISITIONS = 3
202+
203+ /**
204+ * Internal signal: the retained publish target names a file whose lock this write does not
205+ * hold. Thrown only from the innermost lock, so withFileLock unwinds and releases every held
206+ * lock before the retry, and never escapes withBothIdentityLocks.
207+ */
208+ class TargetOutsideHeldLocksError extends Error {
209+ constructor (
210+ readonly targetKey : string ,
211+ readonly heldKeys : readonly string [ ] ,
212+ ) {
213+ super ( `publish target ${ targetKey } is not covered by the held locks ${ heldKeys . join ( ", " ) } ` )
214+ this . name = "TargetOutsideHeldLocksError"
215+ }
216+ }
217+
195218/**
196219 * Acquire the advisory locks covering BOTH identities of a guarded write:
197220 * the resolved referent key every writer to the file uses, and the alias
@@ -201,15 +224,60 @@ async function fixedPublishTarget(absolutePath: string): Promise<string> {
201224 * taken in sorted order, the shared order of that path, so two guarded
202225 * writes can never deadlock, and withFileLock's own unwinding releases them
203226 * inner-first.
227+ *
228+ * The publish target is fixed INSIDE those locks and handed to the operation, which must
229+ * write exactly that path: the version comparison and the publish act on one target, so a
230+ * symlink retargeted after the caller's allowlist check cannot send the write to a file that
231+ * check never covered.
232+ *
233+ * The key of THAT target is then re-derived under the same locks. Both keys above were
234+ * computed from the alias before any lock was held, so a peer that replaces the alias while
235+ * this write is queued - or while it waits behind the FIFO chain - leaves this write holding
236+ * the OLD referent's lock and the alias entry's lock, while the target it is about to publish
237+ * is a different file whose lock belongs to some other writer. Writing it would race that
238+ * writer outright and ship bytes into a path the caller's authorization never covered. When
239+ * that happens the helper unwinds (inner lock first), takes the locks again against the
240+ * alias's CURRENT referent, and re-runs the check; after MAX_LOCK_REACQUISITIONS it rejects
241+ * the write rather than chasing a moving target.
204242 */
205- async function withBothIdentityLocks < T > ( absolutePath : string , operation : ( ) => Promise < T > ) : Promise < T > {
206- const referentKey = await resolveLockKey ( absolutePath )
207- const aliasKey = await resolveLinkPathLockKey ( absolutePath )
208- if ( aliasKey === referentKey ) {
209- return withFileLock ( referentKey , operation )
243+ async function withBothIdentityLocks < T > (
244+ absolutePath : string ,
245+ operation : ( retainedTarget : string ) => Promise < T > ,
246+ ) : Promise < T > {
247+ for ( let attempt = 1 ; ; attempt ++ ) {
248+ const referentKey = await resolveLockKey ( absolutePath )
249+ const aliasKey = await resolveLinkPathLockKey ( absolutePath )
250+ const heldKeys = aliasKey === referentKey ? [ referentKey ] : [ aliasKey , referentKey ]
251+ const lockOrder = [ ...heldKeys ] . sort ( )
252+
253+ const runUnderLocks = async ( index : number ) : Promise < T > => {
254+ if ( index === lockOrder . length ) {
255+ const retainedTarget = await fixedPublishTarget ( absolutePath )
256+ const retainedKey = await resolveLockKey ( retainedTarget )
257+ if ( ! heldKeys . includes ( retainedKey ) ) {
258+ throw new TargetOutsideHeldLocksError ( retainedKey , heldKeys )
259+ }
260+ return operation ( retainedTarget )
261+ }
262+ return withFileLock ( lockOrder [ index ] , ( ) => runUnderLocks ( index + 1 ) )
263+ }
264+
265+ try {
266+ return await runUnderLocks ( 0 )
267+ } catch ( error : unknown ) {
268+ if ( ! ( error instanceof TargetOutsideHeldLocksError ) ) {
269+ throw error
270+ }
271+ if ( attempt >= MAX_LOCK_REACQUISITIONS ) {
272+ throw new GuardRejectedError (
273+ "File was retargeted while this write was queued -- nothing was published; re-read " +
274+ absolutePath +
275+ " and retry." ,
276+ absolutePath ,
277+ )
278+ }
279+ }
210280 }
211- const [ first , second ] = aliasKey < referentKey ? [ aliasKey , referentKey ] : [ referentKey , aliasKey ]
212- return withFileLock ( first , ( ) => withFileLock ( second , operation ) )
213281}
214282
215283export async function createIfAbsent (
@@ -229,9 +297,10 @@ export async function createIfAbsent(
229297 // Lock both identities of the write: the resolved referent every other
230298 // writer to this file uses, and the alias entry a link-swapping protocol
231299 // writer holds.
232- return withBothIdentityLocks ( absolutePath , async ( ) => {
300+ return withBothIdentityLocks ( absolutePath , async ( publishTarget ) => {
233301 cancelledBeforePublish ( absolutePath , displayPath , isCancelled )
234- const publishTarget = await fixedPublishTarget ( absolutePath )
302+ // publishTarget is the retained target the helper fixed under the held locks and verified
303+ // those locks cover.
235304 authorizeTarget ?.( publishTarget )
236305 try {
237306 await fs . access ( publishTarget )
@@ -243,7 +312,9 @@ export async function createIfAbsent(
243312 // Immediately before publication starts.
244313 cancelledBeforePublish ( absolutePath , displayPath , isCancelled )
245314 try {
246- await safeWriteText ( publishTarget , content )
315+ // The retained target was resolved under the held locks: the publish acts on it as given
316+ // rather than resolving the alias a second time.
317+ await safeWriteText ( publishTarget , content , { retainedTarget : true } )
247318 } catch ( error : unknown ) {
248319 // A rename that landed before the durability check failed still placed the
249320 // bytes at the target: hand the token up before the error leaves the lock.
@@ -302,13 +373,12 @@ export async function replaceIfVersion(
302373 // Lock both identities of the write: the resolved referent every other
303374 // writer to this file uses, and the alias entry a link-swapping protocol
304375 // writer holds.
305- return withBothIdentityLocks ( absolutePath , async ( ) => {
376+ return withBothIdentityLocks ( absolutePath , async ( publishTarget ) => {
306377 cancelledBeforePublish ( absolutePath , displayPath , isCancelled )
307- // Resolve and retain the publish target inside the lock: the version
308- // comparison and the publish below both act on this fixed target, so a
309- // symlink retargeted after the caller's allowlist check cannot send the
310- // write to a file the version check never covered.
311- const publishTarget = await fixedPublishTarget ( absolutePath )
378+ // publishTarget is fixed under the held locks and verified to be covered by them: the
379+ // version comparison and the publish below both act on this one target, so a symlink
380+ // retargeted after the caller's allowlist check cannot send the write to a file the
381+ // version check never covered.
312382 authorizeTarget ?.( publishTarget )
313383 let currentVersion : string
314384 try {
@@ -339,7 +409,9 @@ export async function replaceIfVersion(
339409 // Immediately before publication starts.
340410 cancelledBeforePublish ( absolutePath , displayPath , isCancelled )
341411 try {
342- await safeWriteText ( publishTarget , content )
412+ // The retained target was resolved under the held locks: the publish acts on it as given
413+ // rather than resolving the alias a second time.
414+ await safeWriteText ( publishTarget , content , { retainedTarget : true } )
343415 } catch ( error : unknown ) {
344416 // A rename that landed before the durability check failed still placed the
345417 // bytes at the target: hand the token up before the error leaves the lock.
0 commit comments