@indigoai-us/hq-cloud 6.14.10 → 6.14.11

package/src/s3.ts

@@ -253,6 +253,89 @@ function removeTempPath(tempPath: string): void {
   }
 }
 
+export interface ReplaceStagedPathOps {
+  lstat(path: string): fs.Stats;
+  rename(from: string, to: string): void;
+  remove(path: string): void;
+}
+
+const DEFAULT_REPLACE_STAGED_PATH_OPS: ReplaceStagedPathOps = {
+  lstat: (p) => fs.lstatSync(p),
+  rename: (from, to) => fs.renameSync(from, to),
+  remove: (p) => fs.unlinkSync(p),
+};
+
+function replacementBackupPath(localPath: string): string {
+  const dir = path.dirname(localPath);
+  const random = crypto.randomBytes(10).toString("hex");
+  return path.join(dir, `.hq-backup-${random}`);
+}
+
+/**
+ * Install a fully-staged download over its destination.
+ *
+ * A direct rename is atomic and remains the fast path for absent destinations
+ * and ordinary files. Windows cannot rename over an existing directory link,
+ * though, because MoveFileEx treats that link as an existing directory. For a
+ * symlink/junction destination, move the old link to a sibling backup first,
+ * install the staged entry, then remove the backup. Any failure after the
+ * backup move restores the exact prior link before rethrowing.
+ *
+ * The tiny operations seam keeps the Windows failure/rollback contract
+ * deterministic in ESM tests without spying on non-configurable fs exports.
+ */
+export function replaceStagedPath(
+  stagedPath: string,
+  localPath: string,
+  ops: ReplaceStagedPathOps = DEFAULT_REPLACE_STAGED_PATH_OPS,
+): void {
+  let existing: fs.Stats;
+  try {
+    existing = ops.lstat(localPath);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      ops.rename(stagedPath, localPath);
+      return;
+    }
+    throw err;
+  }
+
+  if (!existing.isSymbolicLink()) {
+    ops.rename(stagedPath, localPath);
+    return;
+  }
+
+  const backupPath = replacementBackupPath(localPath);
+  ops.rename(localPath, backupPath);
+  let stagedInstalled = false;
+  try {
+    ops.rename(stagedPath, localPath);
+    stagedInstalled = true;
+    ops.remove(backupPath);
+  } catch (primaryError) {
+    const rollbackErrors: unknown[] = [];
+    if (stagedInstalled) {
+      try {
+        ops.rename(localPath, stagedPath);
+      } catch (rollbackError) {
+        rollbackErrors.push(rollbackError);
+      }
+    }
+    try {
+      ops.rename(backupPath, localPath);
+    } catch (rollbackError) {
+      rollbackErrors.push(rollbackError);
+    }
+    if (rollbackErrors.length > 0) {
+      throw new AggregateError(
+        [primaryError, ...rollbackErrors],
+        "Staged path replacement failed and the previous directory link could not be fully restored",
+      );
+    }
+    throw primaryError;
+  }
+}
+
 async function getObjectStream(
   io: ObjectIO,
   key: string,
@@ -904,7 +987,7 @@ export async function downloadFile(
     try {
       fs.symlinkSync(symlinkTarget, tempPath);
       options.beforeReplace?.();
-      fs.renameSync(tempPath, localPath);
+      replaceStagedPath(tempPath, localPath);
     } catch (err) {
       removeTempPath(tempPath);
       throw err;
@@ -1014,7 +1097,7 @@ export async function downloadFile(
     }
 
     options.beforeReplace?.();
-    fs.renameSync(tempPath, localPath);
+    replaceStagedPath(tempPath, localPath);
     tempReady = false;
   } finally {
     if (tempReady) removeTempPath(tempPath);