@statewalker/webrun-files-node 0.10.5 → 0.11.0

package/README.md

@@ -59,6 +59,26 @@ for await (const chunk of files.read('/large-file.bin', { start: 1000, length: 5
 }
 ```
 
+### A lock file, safe across processes
+
+```typescript
+const content = [new TextEncoder().encode(`${process.pid}\n`)];
+if (await files.createExclusive('/repo/.git/index.lock', content)) {
+  try {
+    // ... only this process gets here until the lock is removed
+  } finally {
+    await files.remove('/repo/.git/index.lock');
+  }
+} else {
+  // another process holds the lock
+}
+```
+
+`createExclusive` opens the file with `O_CREAT | O_EXCL`, so the operating system decides who
+wins: every process on the machine using that filesystem is excluded, and on network file systems
+that honour `O_EXCL` (NFSv3 and later) other machines are too. Anything already at the path,
+including a symbolic link, dangling or not, makes it return `false`.
+
 ### A temporary directory per test
 
 ```typescript
@@ -83,9 +103,10 @@ try {
 | Call | Implementation |
 | --- | --- |
 | `read` | `fs.open` + positioned `handle.read` in 8 KiB buffers, only the requested range |
-| `write` | `fs.mkdir(parent, { recursive: true })`, then collects every chunk and calls `fs.writeFile` once |
+| `write` | `fs.mkdir(parent, { recursive: true })`, then streams the chunks (batched to 64 KiB) into a temporary `.webrun-tmp-<random>` beside the file and renames it over the file |
+| `createExclusive` | `fs.mkdir(parent, { recursive: true })`, then `fs.open(path, "wx")`; `EEXIST` returns `false`, otherwise the chunks are streamed (batched to 64 KiB) straight into the new file, which is unlinked again if the source fails |
 | `list` | `fs.readdir` + `fs.stat` per entry, walked through `listInPathOrder` |
-| `move` | `fs.rename` after creating the target's parent |
+| `move` | `fs.rename` after creating the target's parent: atomic, replaces an existing file or (for a directory) an empty directory |
 | `copy` | `fs.cp(..., { recursive: true })` |
 | `remove` | `fs.rm(..., { recursive: true, force: true })` for a directory, `fs.unlink` for a file |
 
@@ -103,10 +124,38 @@ directory whose whole subtree sorts at or before `after`.
   `NodeFilesApi: path is outside rootDir: /../etc/passwd` (reads throw when iterated). `..` that
   stays inside (`/a/../b.txt`) is fine. Symbolic links inside `rootDir` are followed as the
   operating system follows them, so a link pointing out of `rootDir` still leads out.
-- **`write` holds the whole file in memory** before writing it, so a very large upload costs its
-  full size in RAM. Reads stream.
-- **`move` across devices returns `false`.** It is a single `fs.rename`; when that fails (`EXDEV`,
-  permissions) the method returns `false` instead of falling back to copy and delete.
+- **`write` streams, and replaces the file at the end.** Memory stays at about two batches of
+  64 KiB plus one chunk. Until the rename the old file stays readable, and a source that fails leaves it
+  unchanged. A read-only file is refused, as an in-place write was. Replacing keeps the old
+  file's permission bits (not setuid/setgid, which a write would clear) and writes through a
+  symbolic link to its target (a dangling link is replaced by a regular file, and a link out of
+  `rootDir` is written there, with its temporary beside the target); a hard link is replaced,
+  not written through, and the owner, ACLs and extended
+  attributes are those of a new file. The temporary needs write permission on the directory.
+  `list` hides the temporaries (files named exactly `.webrun-tmp-` plus 16 hex digits); a crash
+  can leave one behind, still visible to `exists`, `stats` and `read`. A caller that reuses
+  a chunk's buffer after yielding it may change what is written (up to 64 KiB is held before
+  each write). Reads stream.
+- **Replacing has the costs of a rename.** The disk must hold the old file and the new one
+  until the rename. The new content is not flushed (`fsync`) before the rename, so after a
+  power loss the file can be empty or partial on some file systems. On Windows a file that
+  another process holds open cannot be replaced, so the rename is retried for about a second
+  before the write fails (the temporary is removed and the old file kept). A file the rename cannot replace because it is a mount point (a
+  bind-mounted file in a container, `EBUSY`) or on another device (`EXDEV`) is written in
+  place instead: the temporary is copied into it, keeping its owner and mode, so readers may
+  see it half-written, and a failure part way (a full disk) leaves it partial.
+- **A lock file is visible while it is written.** Unlike `write`, `createExclusive` writes in
+  place, as git does with its lock files: other readers see the file grow until the content
+  ends. A crash part way leaves the partial file, and with it the lock, behind.
+- **Cleanup unlinks by path.** When the source fails, the file is unlinked by its path. If
+  another process meanwhile removed it as a stale lock and created its own, that file is the one
+  removed. Git's lock files behave the same.
+- **`move` is atomic, and returns `false` when the rename fails.** It is a single `fs.rename`, so
+  a reader sees the old target or the new one, never a missing or partial file, and a failed
+  rename changes nothing. When it fails (a file onto a directory, a directory onto a file or a
+  non-empty directory, a directory into itself, `EXDEV` across devices, permissions) the method
+  returns `false` instead of falling back to copy and delete; the target's parent directories may
+  stay created.
 - **Unreadable reads look like missing files.** `read` swallows every error (missing file,
   permission denied, a directory) and yields nothing; `copy` and `move` return `false`.
 

package/dist/cjs/index.cjs

@@ -139,7 +139,86 @@ function dirname(path) {
 	if (lastSlash <= 0) return "/";
 	return normalized.substring(0, lastSlash);
 }
+// src/replace-file.ts
+/** Windows refuses to replace a file another process holds open; such holds are brief. */
+const WIN32_RETRY_CODES = /* @__PURE__ */ new Set([
+	"EPERM",
+	"EACCES",
+	"EBUSY"
+]);
+const WIN32_RETRIES = 7;
+/**
+* A rename cannot replace a mount point (a bind-mounted file: EBUSY on POSIX) or cross
+* devices (EXDEV). On Windows EBUSY is a sharing violation, retried above, not a mount.
+*/
+const COPY_CODES = /* @__PURE__ */ new Set(["EBUSY", "EXDEV"]);
+const WIN32_COPY_CODES = /* @__PURE__ */ new Set(["EXDEV"]);
+const COPY_CHUNK = 65536;
+const codeOf = (error) => error?.code;
+/**
+* Move `tmp` over `target`. Normally a rename, so readers see the old file or the new one.
+* On Windows a rename refused because the file is open elsewhere is retried for about a
+* second. A rename refused because `target` is a mount point or on another device (EBUSY,
+* EXDEV) falls back to copying `tmp` into `target` in place, as an in-place write would:
+* the target keeps its inode, owner and mode (no chmod, no unlink), and a failure part way
+* leaves it partial. Then `tmp` is removed (best effort). Any other failure is thrown and
+* `tmp` is left to the caller.
+*/
+async function replaceFile(tmp, target, options = {}) {
+	const rename = options.rename ?? node_fs_promises.rename;
+	const win32 = (options.platform ?? process.platform) === "win32";
+	let delay = options.retryDelayMs ?? 10;
+	for (let attempt = 0;; attempt++) try {
+		await rename(tmp, target);
+		return;
+	} catch (error) {
+		const code = codeOf(error);
+		if (win32 && code && WIN32_RETRY_CODES.has(code) && attempt < WIN32_RETRIES) {
+			await new Promise((resolve) => setTimeout(resolve, delay));
+			delay *= 2;
+			continue;
+		}
+		if (code && (win32 ? WIN32_COPY_CODES : COPY_CODES).has(code)) {
+			await copyInto(tmp, target);
+			await node_fs_promises.rm(tmp, { force: true }).catch(() => {});
+			return;
+		}
+		throw error;
+	}
+}
+/** Overwrite `target` in place with `source` (not `fs.copyFile`, which chmods and unlinks). */
+async function copyInto(source, target) {
+	const from = await node_fs_promises.open(source, "r");
+	try {
+		const to = await node_fs_promises.open(target, "r+");
+		try {
+			const buffer = new Uint8Array(COPY_CHUNK);
+			let position = 0;
+			for (;;) {
+				const { bytesRead } = await from.read(buffer, 0, buffer.length, position);
+				if (bytesRead === 0) break;
+				let offset = 0;
+				while (offset < bytesRead) {
+					const { bytesWritten } = await to.write(buffer, offset, bytesRead - offset, position + offset);
+					offset += bytesWritten;
+				}
+				position += bytesRead;
+			}
+			await to.truncate(position);
+		} finally {
+			await to.close();
+		}
+	} finally {
+		await from.close();
+	}
+}
 // src/node-files-api.ts
+/** Small chunks are gathered up to this size before each write call. */
+const WRITE_BATCH = 65536;
+/** Temporaries of writes in flight: hidden from `list`, left behind only by a crash. */
+const TMP_PREFIX = ".webrun-tmp-";
+const TMP_NAME = /^\.webrun-tmp-[0-9a-f]{16}$/;
+const tmpName = () => TMP_PREFIX + Array.from(crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(8)), (b) => b.toString(16).padStart(2, "0")).join("");
 /**
 * Node.js FilesApi implementation using fs/promises.
 * Maps virtual paths (starting with /) to the filesystem rooted at rootDir.
@@ -152,7 +231,8 @@ var NodeFilesApi = class {
 	/** The real path of a virtual one; throws when `..` segments would take it outside rootDir. */
 	resolvePath(virtualPath) {
 		const real = node_path.resolve(this.rootDir, `.${normalizePath(virtualPath)}`);
-		if (real !== this.rootDir && !real.startsWith(this.rootDir + node_path.sep)) throw new Error(`NodeFilesApi: path is outside rootDir: ${virtualPath}`);
+		const prefix = this.rootDir.endsWith(node_path.sep) ? this.rootDir : this.rootDir + node_path.sep;
+		if (real !== this.rootDir && !real.startsWith(prefix)) throw new Error(`NodeFilesApi: path is outside rootDir: ${virtualPath}`);
 		return real;
 	}
 	async *read(path, options) {
@@ -186,23 +266,70 @@ var NodeFilesApi = class {
 		}
 	}
 	async write(path, content) {
-		const realPath = this.resolvePath(path);
+		const resolved = this.resolvePath(path);
+		if (resolved === this.rootDir) throw Object.assign(/* @__PURE__ */ new Error(`EISDIR: cannot write the root directory: ${path}`), { code: "EISDIR" });
 		const normalized = normalizePath(path);
 		const dir = this.resolvePath(dirname(normalized));
 		await node_fs_promises.mkdir(dir, { recursive: true });
-		const chunks = [];
-		let totalLength = 0;
-		for await (const chunk of content) {
-			chunks.push(chunk);
-			totalLength += chunk.length;
+		let realPath = resolved;
+		let mode;
+		let existing;
+		try {
+			if ((await node_fs_promises.lstat(resolved)).isSymbolicLink()) realPath = await node_fs_promises.realpath(resolved);
+			existing = await node_fs_promises.stat(realPath);
+		} catch {}
+		if (existing) {
+			if (existing.isDirectory()) throw Object.assign(/* @__PURE__ */ new Error(`EISDIR: illegal operation on a directory: ${path}`), { code: "EISDIR" });
+			await node_fs_promises.access(realPath, node_fs_promises.constants.W_OK);
+			mode = existing.mode & 511;
 		}
-		const result = new Uint8Array(totalLength);
-		let offset = 0;
-		for (const chunk of chunks) {
-			result.set(chunk, offset);
-			offset += chunk.length;
+		const tmp = node_path.join(node_path.dirname(realPath), tmpName());
+		const handle = await node_fs_promises.open(tmp, "wx");
+		let done = false;
+		try {
+			await writeBatched(handle, content);
+			if (mode !== void 0) await handle.chmod(mode);
+			await handle.close();
+			await replaceFile(tmp, realPath);
+			done = true;
+		} finally {
+			if (!done) {
+				await handle.close().catch(() => {});
+				await node_fs_promises.rm(tmp, { force: true }).catch(() => {});
+			}
+		}
+	}
+	/**
+	* `open(path, "wx")` — `O_CREAT | O_EXCL` — so the operating system decides: exclusive
+	* against every process on the machine using the same filesystem, and on most network
+	* filesystems (NFSv3 and later) across machines too. Anything at the path counts as
+	* existing, a symbolic link included, even a dangling one. The file is visible, growing,
+	* while its content is streamed in (64 KiB batches), as git's lock files are; a source
+	* that fails removes it again.
+	*/
+	async createExclusive(path, content) {
+		const resolved = this.resolvePath(path);
+		if (resolved === this.rootDir) return false;
+		await node_fs_promises.mkdir(this.resolvePath(dirname(normalizePath(path))), { recursive: true });
+		let handle;
+		try {
+			handle = await node_fs_promises.open(resolved, "wx");
+		} catch (error) {
+			if (error.code === "EEXIST") return false;
+			throw error;
+		}
+		let done = false;
+		try {
+			await writeBatched(handle, content);
+			await handle.close();
+			done = true;
+			return true;
+		} finally {
+			if (!done) {
+				await handle.close().catch(() => {});
+				await node_fs_promises.unlink(resolved).catch(() => {});
+			}
 		}
-		await node_fs_promises.writeFile(realPath, result);
 	}
 	async mkdir(path) {
 		const realPath = this.resolvePath(path);
@@ -222,6 +349,7 @@ var NodeFilesApi = class {
 		}
 		const infos = [];
 		for (const entry of entries) {
+			if (entry.isFile() && TMP_NAME.test(entry.name)) continue;
 			const entryPath = joinPath(dir, entry.name);
 			let stat;
 			try {
@@ -279,6 +407,16 @@ var NodeFilesApi = class {
 			return false;
 		}
 	}
+	/**
+	* `fs.rename` (POSIX `rename(2)`), after creating the target's parent directories:
+	* atomic within one filesystem, so a reader sees the old target or the new one, never
+	* a missing or partial file, and a failed rename changes nothing. An existing file is
+	* replaced, and so is an empty directory when the source is a directory. A file onto
+	* a directory (EISDIR), a directory onto a file (ENOTDIR) or a non-empty directory
+	* (ENOTEMPTY), a directory into its own subtree (EINVAL), and any other failed rename
+	* return false, the target untouched. The target's parent directories are created
+	* before the rename, so they may be left behind even when `move` returns false.
+	*/
 	async move(source, target) {
 		const sourcePath = this.resolvePath(source);
 		const targetPath = this.resolvePath(target);
@@ -316,4 +454,27 @@ var NodeFilesApi = class {
 		}
 	}
 };
+/** Write the content to the handle, small chunks gathered into {@link WRITE_BATCH} writes. */
+async function writeBatched(handle, content) {
+	const batch = [];
+	let batched = 0;
+	const flush = async () => {
+		if (batched === 0) return;
+		const bytes = batch.length === 1 ? batch[0] : Buffer.concat(batch);
+		let offset = 0;
+		while (offset < bytes.length) {
+			const { bytesWritten } = await handle.write(bytes, offset, bytes.length - offset);
+			offset += bytesWritten;
+		}
+		batch.length = 0;
+		batched = 0;
+	};
+	for await (const chunk of content) {
+		if (chunk.length === 0) continue;
+		batch.push(chunk);
+		batched += chunk.length;
+		if (batched >= WRITE_BATCH) await flush();
+	}
+	await flush();
+}
 exports.NodeFilesApi = NodeFilesApi;

package/dist/esm/index.js

@@ -115,7 +115,86 @@ function dirname(path) {
 	if (lastSlash <= 0) return "/";
 	return normalized.substring(0, lastSlash);
 }
+// src/replace-file.ts
+/** Windows refuses to replace a file another process holds open; such holds are brief. */
+const WIN32_RETRY_CODES = /* @__PURE__ */ new Set([
+	"EPERM",
+	"EACCES",
+	"EBUSY"
+]);
+const WIN32_RETRIES = 7;
+/**
+* A rename cannot replace a mount point (a bind-mounted file: EBUSY on POSIX) or cross
+* devices (EXDEV). On Windows EBUSY is a sharing violation, retried above, not a mount.
+*/
+const COPY_CODES = /* @__PURE__ */ new Set(["EBUSY", "EXDEV"]);
+const WIN32_COPY_CODES = /* @__PURE__ */ new Set(["EXDEV"]);
+const COPY_CHUNK = 65536;
+const codeOf = (error) => error?.code;
+/**
+* Move `tmp` over `target`. Normally a rename, so readers see the old file or the new one.
+* On Windows a rename refused because the file is open elsewhere is retried for about a
+* second. A rename refused because `target` is a mount point or on another device (EBUSY,
+* EXDEV) falls back to copying `tmp` into `target` in place, as an in-place write would:
+* the target keeps its inode, owner and mode (no chmod, no unlink), and a failure part way
+* leaves it partial. Then `tmp` is removed (best effort). Any other failure is thrown and
+* `tmp` is left to the caller.
+*/
+async function replaceFile(tmp, target, options = {}) {
+	const rename = options.rename ?? fs.rename;
+	const win32 = (options.platform ?? process.platform) === "win32";
+	let delay = options.retryDelayMs ?? 10;
+	for (let attempt = 0;; attempt++) try {
+		await rename(tmp, target);
+		return;
+	} catch (error) {
+		const code = codeOf(error);
+		if (win32 && code && WIN32_RETRY_CODES.has(code) && attempt < WIN32_RETRIES) {
+			await new Promise((resolve) => setTimeout(resolve, delay));
+			delay *= 2;
+			continue;
+		}
+		if (code && (win32 ? WIN32_COPY_CODES : COPY_CODES).has(code)) {
+			await copyInto(tmp, target);
+			await fs.rm(tmp, { force: true }).catch(() => {});
+			return;
+		}
+		throw error;
+	}
+}
+/** Overwrite `target` in place with `source` (not `fs.copyFile`, which chmods and unlinks). */
+async function copyInto(source, target) {
+	const from = await fs.open(source, "r");
+	try {
+		const to = await fs.open(target, "r+");
+		try {
+			const buffer = new Uint8Array(COPY_CHUNK);
+			let position = 0;
+			for (;;) {
+				const { bytesRead } = await from.read(buffer, 0, buffer.length, position);
+				if (bytesRead === 0) break;
+				let offset = 0;
+				while (offset < bytesRead) {
+					const { bytesWritten } = await to.write(buffer, offset, bytesRead - offset, position + offset);
+					offset += bytesWritten;
+				}
+				position += bytesRead;
+			}
+			await to.truncate(position);
+		} finally {
+			await to.close();
+		}
+	} finally {
+		await from.close();
+	}
+}
 // src/node-files-api.ts
+/** Small chunks are gathered up to this size before each write call. */
+const WRITE_BATCH = 65536;
+/** Temporaries of writes in flight: hidden from `list`, left behind only by a crash. */
+const TMP_PREFIX = ".webrun-tmp-";
+const TMP_NAME = /^\.webrun-tmp-[0-9a-f]{16}$/;
+const tmpName = () => TMP_PREFIX + Array.from(crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(8)), (b) => b.toString(16).padStart(2, "0")).join("");
 /**
 * Node.js FilesApi implementation using fs/promises.
 * Maps virtual paths (starting with /) to the filesystem rooted at rootDir.
@@ -128,7 +207,8 @@ var NodeFilesApi = class {
 	/** The real path of a virtual one; throws when `..` segments would take it outside rootDir. */
 	resolvePath(virtualPath) {
 		const real = nodePath.resolve(this.rootDir, `.${normalizePath(virtualPath)}`);
-		if (real !== this.rootDir && !real.startsWith(this.rootDir + nodePath.sep)) throw new Error(`NodeFilesApi: path is outside rootDir: ${virtualPath}`);
+		const prefix = this.rootDir.endsWith(nodePath.sep) ? this.rootDir : this.rootDir + nodePath.sep;
+		if (real !== this.rootDir && !real.startsWith(prefix)) throw new Error(`NodeFilesApi: path is outside rootDir: ${virtualPath}`);
 		return real;
 	}
 	async *read(path, options) {
@@ -162,23 +242,70 @@ var NodeFilesApi = class {
 		}
 	}
 	async write(path, content) {
-		const realPath = this.resolvePath(path);
+		const resolved = this.resolvePath(path);
+		if (resolved === this.rootDir) throw Object.assign(/* @__PURE__ */ new Error(`EISDIR: cannot write the root directory: ${path}`), { code: "EISDIR" });
 		const normalized = normalizePath(path);
 		const dir = this.resolvePath(dirname(normalized));
 		await fs.mkdir(dir, { recursive: true });
-		const chunks = [];
-		let totalLength = 0;
-		for await (const chunk of content) {
-			chunks.push(chunk);
-			totalLength += chunk.length;
+		let realPath = resolved;
+		let mode;
+		let existing;
+		try {
+			if ((await fs.lstat(resolved)).isSymbolicLink()) realPath = await fs.realpath(resolved);
+			existing = await fs.stat(realPath);
+		} catch {}
+		if (existing) {
+			if (existing.isDirectory()) throw Object.assign(/* @__PURE__ */ new Error(`EISDIR: illegal operation on a directory: ${path}`), { code: "EISDIR" });
+			await fs.access(realPath, fs.constants.W_OK);
+			mode = existing.mode & 511;
 		}
-		const result = new Uint8Array(totalLength);
-		let offset = 0;
-		for (const chunk of chunks) {
-			result.set(chunk, offset);
-			offset += chunk.length;
+		const tmp = nodePath.join(nodePath.dirname(realPath), tmpName());
+		const handle = await fs.open(tmp, "wx");
+		let done = false;
+		try {
+			await writeBatched(handle, content);
+			if (mode !== void 0) await handle.chmod(mode);
+			await handle.close();
+			await replaceFile(tmp, realPath);
+			done = true;
+		} finally {
+			if (!done) {
+				await handle.close().catch(() => {});
+				await fs.rm(tmp, { force: true }).catch(() => {});
+			}
+		}
+	}
+	/**
+	* `open(path, "wx")` — `O_CREAT | O_EXCL` — so the operating system decides: exclusive
+	* against every process on the machine using the same filesystem, and on most network
+	* filesystems (NFSv3 and later) across machines too. Anything at the path counts as
+	* existing, a symbolic link included, even a dangling one. The file is visible, growing,
+	* while its content is streamed in (64 KiB batches), as git's lock files are; a source
+	* that fails removes it again.
+	*/
+	async createExclusive(path, content) {
+		const resolved = this.resolvePath(path);
+		if (resolved === this.rootDir) return false;
+		await fs.mkdir(this.resolvePath(dirname(normalizePath(path))), { recursive: true });
+		let handle;
+		try {
+			handle = await fs.open(resolved, "wx");
+		} catch (error) {
+			if (error.code === "EEXIST") return false;
+			throw error;
+		}
+		let done = false;
+		try {
+			await writeBatched(handle, content);
+			await handle.close();
+			done = true;
+			return true;
+		} finally {
+			if (!done) {
+				await handle.close().catch(() => {});
+				await fs.unlink(resolved).catch(() => {});
+			}
 		}
-		await fs.writeFile(realPath, result);
 	}
 	async mkdir(path) {
 		const realPath = this.resolvePath(path);
@@ -198,6 +325,7 @@ var NodeFilesApi = class {
 		}
 		const infos = [];
 		for (const entry of entries) {
+			if (entry.isFile() && TMP_NAME.test(entry.name)) continue;
 			const entryPath = joinPath(dir, entry.name);
 			let stat;
 			try {
@@ -255,6 +383,16 @@ var NodeFilesApi = class {
 			return false;
 		}
 	}
+	/**
+	* `fs.rename` (POSIX `rename(2)`), after creating the target's parent directories:
+	* atomic within one filesystem, so a reader sees the old target or the new one, never
+	* a missing or partial file, and a failed rename changes nothing. An existing file is
+	* replaced, and so is an empty directory when the source is a directory. A file onto
+	* a directory (EISDIR), a directory onto a file (ENOTDIR) or a non-empty directory
+	* (ENOTEMPTY), a directory into its own subtree (EINVAL), and any other failed rename
+	* return false, the target untouched. The target's parent directories are created
+	* before the rename, so they may be left behind even when `move` returns false.
+	*/
 	async move(source, target) {
 		const sourcePath = this.resolvePath(source);
 		const targetPath = this.resolvePath(target);
@@ -292,4 +430,27 @@ var NodeFilesApi = class {
 		}
 	}
 };
+/** Write the content to the handle, small chunks gathered into {@link WRITE_BATCH} writes. */
+async function writeBatched(handle, content) {
+	const batch = [];
+	let batched = 0;
+	const flush = async () => {
+		if (batched === 0) return;
+		const bytes = batch.length === 1 ? batch[0] : Buffer.concat(batch);
+		let offset = 0;
+		while (offset < bytes.length) {
+			const { bytesWritten } = await handle.write(bytes, offset, bytes.length - offset);
+			offset += bytesWritten;
+		}
+		batch.length = 0;
+		batched = 0;
+	};
+	for await (const chunk of content) {
+		if (chunk.length === 0) continue;
+		batch.push(chunk);
+		batched += chunk.length;
+		if (batched >= WRITE_BATCH) await flush();
+	}
+	await flush();
+}
 export { NodeFilesApi };

package/dist/node-files-api.d.ts

@@ -17,6 +17,15 @@ export declare class NodeFilesApi implements FilesApi {
     private resolvePath;
     read(path: string, options?: ReadOptions): AsyncIterable<Uint8Array>;
     write(path: string, content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>): Promise<void>;
+    /**
+     * `open(path, "wx")` — `O_CREAT | O_EXCL` — so the operating system decides: exclusive
+     * against every process on the machine using the same filesystem, and on most network
+     * filesystems (NFSv3 and later) across machines too. Anything at the path counts as
+     * existing, a symbolic link included, even a dangling one. The file is visible, growing,
+     * while its content is streamed in (64 KiB batches), as git's lock files are; a source
+     * that fails removes it again.
+     */
+    createExclusive(path: string, content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>): Promise<boolean>;
     mkdir(path: string): Promise<void>;
     /** `readdir` order is unspecified, so the tree is walked in `comparePaths` order. */
     list(path: string, options?: ListOptions): AsyncIterable<FileInfo>;
@@ -25,6 +34,16 @@ export declare class NodeFilesApi implements FilesApi {
     stats(path: string): Promise<FileStats | undefined>;
     exists(path: string): Promise<boolean>;
     remove(path: string): Promise<boolean>;
+    /**
+     * `fs.rename` (POSIX `rename(2)`), after creating the target's parent directories:
+     * atomic within one filesystem, so a reader sees the old target or the new one, never
+     * a missing or partial file, and a failed rename changes nothing. An existing file is
+     * replaced, and so is an empty directory when the source is a directory. A file onto
+     * a directory (EISDIR), a directory onto a file (ENOTDIR) or a non-empty directory
+     * (ENOTEMPTY), a directory into its own subtree (EINVAL), and any other failed rename
+     * return false, the target untouched. The target's parent directories are created
+     * before the rename, so they may be left behind even when `move` returns false.
+     */
     move(source: string, target: string): Promise<boolean>;
     copy(source: string, target: string): Promise<boolean>;
 }

package/dist/node-files-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node-files-api.d.ts","sourceRoot":"","sources":["../src/node-files-api.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAGnC,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,qBAAa,YAAa,YAAW,QAAQ;IAC3C,OAAO,CAAC,OAAO,CAAS;IAExB,YAAY,OAAO,CAAC,EAAE,mBAAmB,EAExC;IAED,+FAA+F;IAC/F,OAAO,CAAC,WAAW;IAQZ,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC,CAyC1E;IAEK,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC,CAuBf;IAEK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvC;IAED,qFAAqF;IAC9E,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC,CAExE;IAED,mFAAmF;YACrE,YAAY;IAgCpB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAkBxD;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAS3C;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAc3C;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAmB3D;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAmB3D;CACF"}
+{"version":3,"file":"node-files-api.d.ts","sourceRoot":"","sources":["../src/node-files-api.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAgBnC,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,qBAAa,YAAa,YAAW,QAAQ;IAC3C,OAAO,CAAC,OAAO,CAAS;IAExB,YAAY,OAAO,CAAC,EAAE,mBAAmB,EAExC;IAED,+FAA+F;IAC/F,OAAO,CAAC,WAAW;IASZ,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC,CAyC1E;IAEK,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC,CAwDf;IAED;;;;;;;OAOG;IACG,eAAe,CACnB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,OAAO,CAAC,CA2BlB;IAEK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvC;IAED,qFAAqF;IAC9E,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC,CAExE;IAED,mFAAmF;YACrE,YAAY;IAiCpB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAkBxD;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAS3C;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAc3C;IAED;;;;;;;;;OASG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAmB3D;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAmB3D;CACF"}

package/dist/replace-file.d.ts

@@ -0,0 +1,19 @@
+export interface ReplaceFileOptions {
+    /** The rename to use (tests inject failures). */
+    rename?: (from: string, to: string) => Promise<void>;
+    /** The platform whose rename rules apply (default: `process.platform`). */
+    platform?: string;
+    /** Delay before the first Windows retry; it doubles each time (default 10 ms). */
+    retryDelayMs?: number;
+}
+/**
+ * Move `tmp` over `target`. Normally a rename, so readers see the old file or the new one.
+ * On Windows a rename refused because the file is open elsewhere is retried for about a
+ * second. A rename refused because `target` is a mount point or on another device (EBUSY,
+ * EXDEV) falls back to copying `tmp` into `target` in place, as an in-place write would:
+ * the target keeps its inode, owner and mode (no chmod, no unlink), and a failure part way
+ * leaves it partial. Then `tmp` is removed (best effort). Any other failure is thrown and
+ * `tmp` is left to the caller.
+ */
+export declare function replaceFile(tmp: string, target: string, options?: ReplaceFileOptions): Promise<void>;
+//# sourceMappingURL=replace-file.d.ts.map

package/dist/replace-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replace-file.d.ts","sourceRoot":"","sources":["../src/replace-file.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,kBAAkB;IACjC,iDAAiD;IACjD,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAgBD;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,IAAI,CAAC,CAuBf"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-files-node",
-  "version": "0.10.5",
+  "version": "0.11.0",
   "private": false,
   "type": "module",
   "description": "Node.js FilesApi implementation",
@@ -34,7 +34,7 @@
     "src"
   ],
   "dependencies": {
-    "@statewalker/webrun-files": "^0.10.5"
+    "@statewalker/webrun-files": "^0.11.0"
   },
   "devDependencies": {
     "@types/node": "^26.6.4",

package/src/node-files-api.ts

@@ -9,6 +9,19 @@ import type {
   ReadOptions,
 } from "@statewalker/webrun-files";
 import { dirname, joinPath, listInPathOrder, normalizePath } from "@statewalker/webrun-files";
+import { replaceFile } from "./replace-file.js";
+
+/** Small chunks are gathered up to this size before each write call. */
+const WRITE_BATCH = 64 * 1024;
+
+/** Temporaries of writes in flight: hidden from `list`, left behind only by a crash. */
+const TMP_PREFIX = ".webrun-tmp-";
+const TMP_NAME = /^\.webrun-tmp-[0-9a-f]{16}$/;
+const tmpName = () =>
+  TMP_PREFIX +
+  Array.from(crypto.getRandomValues(new Uint8Array(8)), (b) =>
+    b.toString(16).padStart(2, "0"),
+  ).join("");
 
 export interface NodeFilesApiOptions {
   /**
@@ -32,7 +45,8 @@ export class NodeFilesApi implements FilesApi {
   /** The real path of a virtual one; throws when `..` segments would take it outside rootDir. */
   private resolvePath(virtualPath: string): string {
     const real = nodePath.resolve(this.rootDir, `.${normalizePath(virtualPath)}`);
-    if (real !== this.rootDir && !real.startsWith(this.rootDir + nodePath.sep)) {
+    const prefix = this.rootDir.endsWith(nodePath.sep) ? this.rootDir : this.rootDir + nodePath.sep;
+    if (real !== this.rootDir && !real.startsWith(prefix)) {
       throw new Error(`NodeFilesApi: path is outside rootDir: ${virtualPath}`);
     }
     return real;
@@ -85,28 +99,101 @@ export class NodeFilesApi implements FilesApi {
     path: string,
     content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>,
   ): Promise<void> {
-    const realPath = this.resolvePath(path);
+    const resolved = this.resolvePath(path);
+    if (resolved === this.rootDir) {
+      throw Object.assign(new Error(`EISDIR: cannot write the root directory: ${path}`), {
+        code: "EISDIR",
+      });
+    }
     const normalized = normalizePath(path);
     const dir = this.resolvePath(dirname(normalized));
 
     await fs.mkdir(dir, { recursive: true });
 
-    const chunks: Uint8Array[] = [];
-    let totalLength = 0;
-
-    for await (const chunk of content) {
-      chunks.push(chunk);
-      totalLength += chunk.length;
+    // An existing file keeps what an in-place write kept: a symbolic link is written
+    // through to its target, and the new file gets the old file's mode.
+    // (A dangling link is replaced by a regular file rather than creating its target.)
+    let realPath = resolved;
+    let mode: number | undefined;
+    let existing: Stats | undefined;
+    try {
+      const st = await fs.lstat(resolved);
+      if (st.isSymbolicLink()) realPath = await fs.realpath(resolved);
+      existing = await fs.stat(realPath);
+    } catch {
+      // a new file (or a dangling link): written as a new file
+    }
+    if (existing) {
+      if (existing.isDirectory()) {
+        throw Object.assign(new Error(`EISDIR: illegal operation on a directory: ${path}`), {
+          code: "EISDIR",
+        });
+      }
+      // A rename would replace a file the caller may not write: refuse, as writeFile did.
+      await fs.access(realPath, fs.constants.W_OK);
+      // Permission bits only: setuid/setgid are dropped, as the kernel drops them on a write.
+      mode = existing.mode & 0o777;
     }
 
-    const result = new Uint8Array(totalLength);
-    let offset = 0;
-    for (const chunk of chunks) {
-      result.set(chunk, offset);
-      offset += chunk.length;
+    // Stream into a temporary beside the file, then rename it over the file: memory stays at
+    // about one batch, a source that fails leaves the old file, and a file can be rewritten
+    // from its own read. The short dot-name works for names near the length limit, and
+    // `list` does not show it.
+    const tmp = nodePath.join(nodePath.dirname(realPath), tmpName());
+    const handle = await fs.open(tmp, "wx");
+    let done = false;
+    try {
+      await writeBatched(handle, content);
+      if (mode !== undefined) await handle.chmod(mode);
+      await handle.close();
+      await replaceFile(tmp, realPath);
+      done = true;
+    } finally {
+      if (!done) {
+        await handle.close().catch(() => {});
+        await fs.rm(tmp, { force: true }).catch(() => {});
+      }
     }
+  }
 
-    await fs.writeFile(realPath, result);
+  /**
+   * `open(path, "wx")` — `O_CREAT | O_EXCL` — so the operating system decides: exclusive
+   * against every process on the machine using the same filesystem, and on most network
+   * filesystems (NFSv3 and later) across machines too. Anything at the path counts as
+   * existing, a symbolic link included, even a dangling one. The file is visible, growing,
+   * while its content is streamed in (64 KiB batches), as git's lock files are; a source
+   * that fails removes it again.
+   */
+  async createExclusive(
+    path: string,
+    content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>,
+  ): Promise<boolean> {
+    const resolved = this.resolvePath(path);
+    if (resolved === this.rootDir) return false; // the root always exists
+    await fs.mkdir(this.resolvePath(dirname(normalizePath(path))), { recursive: true });
+
+    let handle: fs.FileHandle;
+    try {
+      handle = await fs.open(resolved, "wx");
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "EEXIST") return false;
+      throw error;
+    }
+    let done = false;
+    try {
+      await writeBatched(handle, content);
+      await handle.close();
+      done = true;
+      return true;
+    } finally {
+      if (!done) {
+        await handle.close().catch(() => {});
+        // Unlinks by path, not by handle: if another process removed our file meanwhile
+        // (taking it for a stale lock) and created its own, this removes theirs. Git's
+        // lock files behave the same.
+        await fs.unlink(resolved).catch(() => {});
+      }
+    }
   }
 
   async mkdir(path: string): Promise<void> {
@@ -130,6 +217,7 @@ export class NodeFilesApi implements FilesApi {
     }
     const infos: FileInfo[] = [];
     for (const entry of entries) {
+      if (entry.isFile() && TMP_NAME.test(entry.name)) continue; // a write in flight
       const entryPath = joinPath(dir, entry.name);
       let stat: Stats;
       try {
@@ -199,6 +287,16 @@ export class NodeFilesApi implements FilesApi {
     }
   }
 
+  /**
+   * `fs.rename` (POSIX `rename(2)`), after creating the target's parent directories:
+   * atomic within one filesystem, so a reader sees the old target or the new one, never
+   * a missing or partial file, and a failed rename changes nothing. An existing file is
+   * replaced, and so is an empty directory when the source is a directory. A file onto
+   * a directory (EISDIR), a directory onto a file (ENOTDIR) or a non-empty directory
+   * (ENOTEMPTY), a directory into its own subtree (EINVAL), and any other failed rename
+   * return false, the target untouched. The target's parent directories are created
+   * before the rename, so they may be left behind even when `move` returns false.
+   */
   async move(source: string, target: string): Promise<boolean> {
     const sourcePath = this.resolvePath(source);
     const targetPath = this.resolvePath(target);
@@ -241,3 +339,30 @@ export class NodeFilesApi implements FilesApi {
     }
   }
 }
+
+/** Write the content to the handle, small chunks gathered into {@link WRITE_BATCH} writes. */
+async function writeBatched(
+  handle: fs.FileHandle,
+  content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>,
+): Promise<void> {
+  const batch: Uint8Array[] = [];
+  let batched = 0;
+  const flush = async () => {
+    if (batched === 0) return;
+    const bytes = batch.length === 1 ? (batch[0] as Uint8Array) : Buffer.concat(batch);
+    let offset = 0;
+    while (offset < bytes.length) {
+      const { bytesWritten } = await handle.write(bytes, offset, bytes.length - offset);
+      offset += bytesWritten;
+    }
+    batch.length = 0;
+    batched = 0;
+  };
+  for await (const chunk of content) {
+    if (chunk.length === 0) continue;
+    batch.push(chunk);
+    batched += chunk.length;
+    if (batched >= WRITE_BATCH) await flush();
+  }
+  await flush();
+}

package/src/replace-file.ts

@@ -0,0 +1,94 @@
+import * as fs from "node:fs/promises";
+
+export interface ReplaceFileOptions {
+  /** The rename to use (tests inject failures). */
+  rename?: (from: string, to: string) => Promise<void>;
+  /** The platform whose rename rules apply (default: `process.platform`). */
+  platform?: string;
+  /** Delay before the first Windows retry; it doubles each time (default 10 ms). */
+  retryDelayMs?: number;
+}
+
+/** Windows refuses to replace a file another process holds open; such holds are brief. */
+const WIN32_RETRY_CODES = new Set(["EPERM", "EACCES", "EBUSY"]);
+const WIN32_RETRIES = 7; // 10 ms doubling: about 1.3 s in all
+
+/**
+ * A rename cannot replace a mount point (a bind-mounted file: EBUSY on POSIX) or cross
+ * devices (EXDEV). On Windows EBUSY is a sharing violation, retried above, not a mount.
+ */
+const COPY_CODES = new Set(["EBUSY", "EXDEV"]);
+const WIN32_COPY_CODES = new Set(["EXDEV"]);
+const COPY_CHUNK = 64 * 1024;
+
+const codeOf = (error: unknown) => (error as { code?: string } | null)?.code;
+
+/**
+ * Move `tmp` over `target`. Normally a rename, so readers see the old file or the new one.
+ * On Windows a rename refused because the file is open elsewhere is retried for about a
+ * second. A rename refused because `target` is a mount point or on another device (EBUSY,
+ * EXDEV) falls back to copying `tmp` into `target` in place, as an in-place write would:
+ * the target keeps its inode, owner and mode (no chmod, no unlink), and a failure part way
+ * leaves it partial. Then `tmp` is removed (best effort). Any other failure is thrown and
+ * `tmp` is left to the caller.
+ */
+export async function replaceFile(
+  tmp: string,
+  target: string,
+  options: ReplaceFileOptions = {},
+): Promise<void> {
+  const rename = options.rename ?? fs.rename;
+  const win32 = (options.platform ?? process.platform) === "win32";
+  let delay = options.retryDelayMs ?? 10;
+  for (let attempt = 0; ; attempt++) {
+    try {
+      await rename(tmp, target);
+      return;
+    } catch (error) {
+      const code = codeOf(error);
+      if (win32 && code && WIN32_RETRY_CODES.has(code) && attempt < WIN32_RETRIES) {
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        delay *= 2;
+        continue;
+      }
+      if (code && (win32 ? WIN32_COPY_CODES : COPY_CODES).has(code)) {
+        await copyInto(tmp, target);
+        await fs.rm(tmp, { force: true }).catch(() => {}); // the content has landed
+        return;
+      }
+      throw error;
+    }
+  }
+}
+
+/** Overwrite `target` in place with `source` (not `fs.copyFile`, which chmods and unlinks). */
+async function copyInto(source: string, target: string): Promise<void> {
+  const from = await fs.open(source, "r");
+  try {
+    const to = await fs.open(target, "r+");
+    try {
+      const buffer = new Uint8Array(COPY_CHUNK);
+      let position = 0;
+      for (;;) {
+        const { bytesRead } = await from.read(buffer, 0, buffer.length, position);
+        if (bytesRead === 0) break;
+        let offset = 0;
+        while (offset < bytesRead) {
+          const { bytesWritten } = await to.write(
+            buffer,
+            offset,
+            bytesRead - offset,
+            position + offset,
+          );
+          offset += bytesWritten;
+        }
+        position += bytesRead;
+      }
+      await to.truncate(position);
+    } finally {
+      await to.close();
+    }
+  } finally {
+    await from.close();
+  }
+}