From d3f498ceec65e4f61f39036ab943ace7ef1b9de5 Mon Sep 17 00:00:00 2001 From: Vinay Prasad <100485512+vinay121314@users.noreply.github.com> Date: Tue, 6 Oct 2026 19:57:57 +0530 Subject: [PATCH] docs(hopper): document HopperTargetLease realpath fallback (#711) * docs(hopper): document HopperTargetLease realpath fallback Closes #642 * docs(hopper): clarify realpath fallback errors --------- Co-authored-by: morluto <76467478+morluto@users.noreply.github.com> --- src/hopper/HopperTargetLease.ts | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/hopper/HopperTargetLease.ts b/src/hopper/HopperTargetLease.ts index 9203c7c77..d07518781 100644 --- a/src/hopper/HopperTargetLease.ts +++ b/src/hopper/HopperTargetLease.ts @@ -35,6 +35,13 @@ export const acquireHopperTargetLease = async (input: { }): Promise => { const directory = input.directory ?? leaseDirectory; await ensureLeaseDirectory(directory); + // The canonical path only derives the lease key; it never authorizes access. + // Common expected `realpath` failures include a missing target or path + // component (ENOENT, ENOTDIR), an unreadable component (EACCES), or a + // symlink loop (ELOOP). This catch also falls back for every other error, + // which may hide a real filesystem problem. The lexical `resolve` fallback + // still yields a deterministic key, but aliases may take separate leases + // whenever `realpath` cannot resolve them. const targetPath = await realpath(input.targetPath).catch(() => resolve(input.targetPath), );