@zenfs/core 2.5.8 → 2.6.0

package/tests/fs/watch.test.ts

@@ -2,7 +2,7 @@
 import type { Stats } from '@zenfs/core';
 import assert from 'node:assert/strict';
 import { suite, test } from 'node:test';
-import { fs } from '../common.js';
+import { config, fs } from '../common.js';
 
 const testDir = '/test-watch-dir';
 const testFile = testDir + '/test.txt';
@@ -10,10 +10,22 @@ const testFile = testDir + '/test.txt';
 await fs.promises.mkdir(testDir);
 await fs.promises.writeFile(testFile, 'Initial content');
 
+/** Fail instead of hanging the suite if an expected event is never emitted */
+async function withTimeout<T>(promise: Promise<T>, ms: number = 1000): Promise<T> {
+	const { promise: timedOut, reject } = Promise.withResolvers<never>();
+	const timer = setTimeout(() => reject(new Error(`Timed out after ${ms} ms waiting for an event`)), ms);
+	timer.unref?.();
+	try {
+		return await Promise.race([promise, timedOut]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
 /**
  * @todo convert `using watcher = ...` to void discards pending ES proposal
  */
-suite('Watch', () => {
+suite('Watch', config('watch'), () => {
 	test('Events emitted on file change', async () => {
 		const { promise, resolve } = Promise.withResolvers<[string, string]>();
 
@@ -24,31 +36,47 @@ suite('Watch', () => {
 		// Modify the file to trigger the event
 		await fs.promises.writeFile(testFile, 'Updated content');
 
-		const [eventType, filename] = await promise;
+		const [eventType, filename] = await withTimeout(promise);
 		assert.equal(eventType, 'change');
 		assert.equal(filename, 'test.txt');
 	});
 
 	test('Events are emitted on delete', async () => {
+		const { promise, resolve } = Promise.withResolvers<string>();
+
+		/* Only wait for the 'rename'. Deleting a watched file changes its link count,
+		which some implementations report as a 'change' event first. */
 		using watcher = fs.watch(testFile, (eventType, filename) => {
-			assert.equal(eventType, 'rename');
-			assert.equal(filename, 'test.txt');
+			if (eventType == 'rename') resolve(filename);
 		});
 
 		// Delete the file to trigger the event
 		await fs.promises.unlink(testFile);
+
+		assert.equal(await withTimeout(promise), 'test.txt');
 	});
 
 	test('Changes are detected with watchFile()', async () => {
-		const listener = (curr: Stats, prev: Stats) => {
-			assert(curr.mtimeMs != prev.mtimeMs);
-			fs.unwatchFile(testFile, listener);
-		};
+		// The previous test deleted the file, and watching a non-existent file is its own can of worms
+		await fs.promises.writeFile(testFile, 'Restored');
 
-		fs.watchFile(testFile, listener);
+		// Timestamps have millisecond resolution, so make sure the two writes can not share one
+		await new Promise(resolve => setImmediate(resolve));
 
-		// Modify the file to trigger the event
-		await fs.promises.writeFile(testFile, 'Changed content');
+		const { promise, resolve } = Promise.withResolvers<[Stats, Stats]>();
+		const listener = (curr: Stats, prev: Stats) => resolve([curr, prev]);
+
+		fs.watchFile(testFile, { interval: 50 }, listener);
+
+		try {
+			// Modify the file to trigger the event
+			await fs.promises.writeFile(testFile, 'Changed content');
+
+			const [curr, prev] = await withTimeout(promise, 2000);
+			assert(curr.mtimeMs != prev.mtimeMs);
+		} finally {
+			fs.unwatchFile(testFile, listener);
+		}
 	});
 
 	test('unwatchFile() works', async () => {
@@ -69,12 +97,18 @@ suite('Watch', () => {
 	});
 
 	test('Directories can be watched', async () => {
+		const { promise, resolve } = Promise.withResolvers<[string, string]>();
+
 		using watcher = fs.watch(testDir, (eventType, filename) => {
-			assert.equal(eventType, 'change');
-			assert.equal(filename, 'newFile.txt');
+			resolve([eventType, filename]);
 		});
 
 		await fs.promises.writeFile(testDir + '/newFile.txt', 'Content');
+
+		const [eventType, filename] = await withTimeout(promise);
+		// Creating the file adds an entry to the directory, which is a 'rename' event
+		assert.equal(eventType, 'rename');
+		assert.equal(filename, 'newFile.txt');
 	});
 
 	test('File renames are detected', async () => {
@@ -84,24 +118,22 @@ suite('Watch', () => {
 		const newFile = testDir + '/' + newFileName;
 
 		await fs.promises.writeFile(oldFile, 'Some content');
-		const oldFileResolver = Promise.withResolvers<void>();
-		const newFileResolver = Promise.withResolvers<void>();
 
-		const fileResolvers: Record<string, { resolver: PromiseWithResolvers<void>; eventType: string }> = {
-			[oldFileName]: { resolver: oldFileResolver, eventType: 'rename' },
-			[newFileName]: { resolver: newFileResolver, eventType: 'change' },
-		};
+		const events: Record<string, string> = {};
+		const { promise, resolve } = Promise.withResolvers<void>();
 
 		using watcher = fs.watch(testDir, (eventType, filename) => {
-			const resolver = fileResolvers[filename];
-			assert.notEqual(resolver, undefined); // should have a resolver so file is expected
-			assert.equal(eventType, resolver.eventType);
-			resolver.resolver.resolve();
+			events[filename] ??= eventType;
+			if (oldFileName in events && newFileName in events) resolve();
 		});
 
-		// Rename the file to trigger the event
+		// Rename the file to trigger the events
 		await fs.promises.rename(oldFile, newFile);
-		await Promise.all([newFileResolver.promise, oldFileResolver.promise]);
+
+		await withTimeout(promise);
+		// Both names are 'rename': one entry disappears and another appears
+		assert.equal(events[oldFileName], 'rename');
+		assert.equal(events[newFileName], 'rename');
 	});
 
 	test('File deletions are detected', async () => {
@@ -109,12 +141,16 @@ suite('Watch', () => {
 
 		await fs.promises.writeFile(tempFile, 'Temporary content');
 
+		const { promise, resolve } = Promise.withResolvers<string>();
+
+		// Only wait for the 'rename', see 'Events are emitted on delete'
 		using watcher = fs.watch(tempFile, (eventType, filename) => {
-			assert.equal(eventType, 'rename');
-			assert.equal(filename, 'tempFile.txt');
+			if (eventType == 'rename') resolve(filename);
 		});
 
 		await fs.promises.unlink(tempFile);
+
+		assert.equal(await withTimeout(promise), 'tempFile.txt');
 	});
 
 	test('File deletions are detected by promises API', async () => {
@@ -122,39 +158,59 @@ suite('Watch', () => {
 
 		await fs.promises.writeFile(tempFile, 'Temporary content');
 
-		const watcher = fs.promises.watch(tempFile);
+		const ac = new AbortController();
+		const watcher = fs.promises.watch(tempFile, { signal: ac.signal });
 
+		// Only wait for the 'rename', see 'Events are emitted on delete'
 		const promise = (async () => {
-			for await (const event of watcher) {
-				assert.equal(event.eventType, 'rename');
-				assert.equal(event.filename, 'tempFile.txt');
-				return;
-			}
-		})();
+			for await (const event of watcher) if (event.eventType == 'rename') return event;
+		})().catch((e: Error) => {
+			if (e.name != 'AbortError') throw e;
+		});
 
-		await fs.promises.unlink(tempFile);
-		await watcher.return!();
-		await promise;
+		try {
+			await fs.promises.unlink(tempFile);
+
+			const event = await withTimeout(promise);
+			assert.equal(event?.eventType, 'rename');
+			assert.equal(event?.filename, 'tempFile.txt');
+		} finally {
+			/* Abort before return(): a native iterator suspended awaiting an event
+			queues return() behind that await, which never resolves */
+			ac.abort();
+			await watcher.return?.();
+		}
 	});
 
 	test('File creations are detected recursively', async () => {
 		const subDir = `${testDir}/sub-dir`;
 		const tempFile = `${subDir}/tempFile.txt`;
 		await fs.promises.mkdir(subDir);
-		const watcher = fs.promises.watch('/');
 
+		const ac = new AbortController();
+		const watcher = fs.promises.watch('/', { recursive: true, signal: ac.signal });
+
+		// Create the file before consuming the iterator, so the first observed event is the unlink
 		await fs.promises.writeFile(tempFile, 'Temporary content');
+
 		const promise = (async () => {
-			for await (const event of watcher) {
-				assert.equal(event.eventType, 'rename');
-				assert.equal(event.filename, tempFile.slice(1));
-				return;
-			}
-		})();
+			for await (const event of watcher) return event;
+		})().catch((e: Error) => {
+			if (e.name != 'AbortError') throw e;
+		});
 
-		await fs.promises.unlink(tempFile);
-		await watcher.return!();
-		await promise;
+		try {
+			await fs.promises.unlink(tempFile);
+
+			const event = await withTimeout(promise);
+			assert.equal(event?.eventType, 'rename');
+			assert.equal(event?.filename, tempFile.slice(1));
+		} finally {
+			/* Abort before return(): a native iterator suspended awaiting an event
+			queues return() behind that await, which never resolves */
+			ac.abort();
+			await watcher.return?.();
+		}
 	});
 
 	test('watch("/") receives events for files under root #293', async () => {
@@ -168,11 +224,9 @@ suite('Watch', () => {
 
 		await fs.promises.writeFile('/watch-root-file.txt', 'x');
 
-		const [eventType, filename] = await Promise.race([
-			promise,
-			new Promise<[string, string]>((_, reject) => setTimeout(() => reject(new Error('watch("/") timed out')), 1000)),
-		]);
-		assert.equal(eventType, 'change');
+		const [eventType, filename] = await withTimeout(promise);
+		// Creating the file adds an entry to the root directory, which is a 'rename' event
+		assert.equal(eventType, 'rename');
 		assert.equal(filename, 'watch-root-file.txt');
 	});
 });

package/tests/fs/write.test.ts

@@ -3,14 +3,14 @@ import assert from 'node:assert/strict';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path/posix';
 import { suite, test } from 'node:test';
-import { fs } from '../common.js';
+import { config, fs } from '../common.js';
 import { data as dataPath } from '../setup.js';
 
 const fileName = 'write.txt';
 const utf8example = readFileSync(join(dataPath, 'utf8.txt'), 'utf8');
 
-suite('Writes', () => {
-	test('Using FileHandle and UTF-8', async () => {
+suite('Writes', config('write'), () => {
+	test('Using FileHandle and UTF-8', config('async'), async () => {
 		const expected = 'ümlaut.';
 
 		const handle = await fs.promises.open(fileName, 'w', 0o644);
@@ -25,7 +25,7 @@ suite('Writes', () => {
 		await fs.promises.unlink(fileName);
 	});
 
-	test('Using FileHandle with buffer', async () => {
+	test('Using FileHandle with buffer', config('async'), async () => {
 		const expected = Buffer.from('hello');
 
 		const handle = await fs.promises.open(fileName, 'w', 0o644);
@@ -41,7 +41,7 @@ suite('Writes', () => {
 		await fs.promises.unlink(fileName);
 	});
 
-	test('Using sync path functions', () => {
+	test('Using sync path functions', config('sync'), () => {
 		const fd = fs.openSync(fileName, 'w');
 
 		let written = fs.writeSync(fd, '');
@@ -58,7 +58,7 @@ suite('Writes', () => {
 		assert.equal(fs.readFileSync(fileName, 'utf8'), 'foobár');
 	});
 
-	test('Using promises API', async () => {
+	test('Using promises API', config('async'), async () => {
 		const filename = 'test.txt';
 		await fs.promises.writeFile(filename, utf8example);
 		const data = await fs.promises.readFile(filename);
@@ -66,7 +66,7 @@ suite('Writes', () => {
 		await fs.promises.unlink(filename);
 	});
 
-	test('Using promises API with buffer', async () => {
+	test('Using promises API with buffer', config('async'), async () => {
 		const filename = 'test2.txt';
 		const expected = Buffer.from(utf8example, 'utf8');
 
@@ -77,7 +77,7 @@ suite('Writes', () => {
 		await fs.promises.unlink(filename);
 	});
 
-	test('Promises API with base64 data', async () => {
+	test('Promises API with base64 data', config('async'), async () => {
 		const data = readFileSync(join(dataPath, 'image.jpg'), 'base64');
 
 		const buffer = Buffer.from(data, 'base64');
@@ -89,7 +89,7 @@ suite('Writes', () => {
 		assert.equal(read, data);
 	});
 
-	test('Using sync path functions with custom mode', () => {
+	test('Using sync path functions with custom mode', config('sync', 'permissions'), () => {
 		const file = 'testWriteFileSync.txt';
 		const mode = 0o755;
 
@@ -102,7 +102,7 @@ suite('Writes', () => {
 		fs.unlinkSync(file);
 	});
 
-	test('Appending to a file synchronously with custom mode', () => {
+	test('Appending to a file synchronously with custom mode', config('sync', 'appends', 'permissions'), () => {
 		const file = 'testAppendFileSync.txt';
 		const mode = 0o755;
 

package/tests/fs/xattr.test.ts

@@ -2,9 +2,9 @@
 import { Buffer } from 'buffer';
 import assert from 'node:assert/strict';
 import { suite, test } from 'node:test';
-import { fs } from '../common.js';
+import { config, fs } from '../common.js';
 
-suite('Extended Attributes', () => {
+suite('Extended Attributes', config('xattr'), () => {
 	const testFile = 'xattr-test.txt';
 	const testValue = 'test value';
 	const testName = 'user.test';
@@ -63,7 +63,7 @@ suite('Extended Attributes', () => {
 		await assert.rejects(fs.xattr.set('nonexistent-file.txt', testName, 'value'), { code: 'ENOENT' });
 	});
 
-	test('synchronous operations', () => {
+	test('synchronous operations', config('sync'), () => {
 		const syncAttrName = 'user.sync-test';
 
 		fs.xattr.setSync(testFile, syncAttrName, testValue);

package/tests/native/run.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+
+sudo npx zenfs-test -v tests/native/setup.ts

package/tests/native/setup.ts

@@ -0,0 +1,230 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+/* Run the FS test suite against native node:fs.
+Since the tests use absolute paths, everything is contained to a scratch directory using chroot-style path mapping. */
+import * as native from 'node:fs';
+import type { TestFlag, TestFlagState } from '../common.js';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { copySync, data, tmp } from '../setup.js';
+import { styleText } from 'node:util';
+
+// The tests assume modes are used as-is, but native fs applies the process umask
+process.umask(0);
+
+// Test files run in parallel processes, so each process gets its own scratch directory
+const root = native.mkdtempSync(join(tmp, 'native-'));
+
+/** Restore directory modes so the scratch directory can be removed (e.g. after permissions tests chmod 0o000) */
+function makeRemovable(path: string): void {
+	try {
+		if (!native.lstatSync(path).isDirectory()) return;
+		native.chmodSync(path, 0o755);
+		for (const entry of native.readdirSync(path)) makeRemovable(join(path, entry));
+	} catch {
+		// The cleanup is best-effort; rmSync will report anything unremovable
+	}
+}
+
+process.on('exit', () => {
+	makeRemovable(root);
+	native.rmSync(root, { recursive: true, force: true });
+});
+
+type PathLike = string | Buffer | URL;
+
+function isPath(value: unknown): value is PathLike {
+	return typeof value == 'string' || value instanceof Buffer || value instanceof URL;
+}
+
+/** Translate a test path into the scratch directory */
+function toNative(path: PathLike): string {
+	if (path instanceof URL) path = fileURLToPath(path);
+	path = path.toString();
+	// Do not map the empty path, so it still results in ENOENT
+	if (!path) return path;
+	return join(root, resolve('/', path));
+}
+
+/** Translate a native path back into a test path */
+function fromNative(path: string): string {
+	return resolve('/', relative(root, path));
+}
+
+/** How many leading arguments are paths */
+const pathArgs: Record<string, number> = {
+	access: 1,
+	appendFile: 1,
+	chmod: 1,
+	chown: 1,
+	copyFile: 2,
+	cp: 2,
+	createReadStream: 1,
+	createWriteStream: 1,
+	exists: 1,
+	glob: 1,
+	lchmod: 1,
+	lchown: 1,
+	link: 2,
+	lstat: 1,
+	lutimes: 1,
+	mkdir: 1,
+	mkdtemp: 1,
+	mkdtempDisposable: 1,
+	open: 1,
+	opendir: 1,
+	readFile: 1,
+	readdir: 1,
+	readlink: 1,
+	realpath: 1,
+	rename: 2,
+	rm: 1,
+	rmdir: 1,
+	stat: 1,
+	statfs: 1,
+	truncate: 1,
+	unlink: 1,
+	unwatchFile: 1,
+	utimes: 1,
+	watch: 1,
+	watchFile: 1,
+	writeFile: 1,
+};
+
+/** Functions whose result is a path that needs to be translated back. Note `mkdir` returns the first created path when recursive */
+const returnsPath = new Set(['realpath', 'mkdtemp', 'readlink', 'mkdir']);
+
+function mapArgs(base: string, args: unknown[]): unknown[] {
+	const out = [...args];
+
+	if (base == 'symlink') {
+		/* Absolute targets must be mapped so resolution can't escape the scratch directory.
+		Relative targets resolve against the link's parent, which is already inside. */
+		if (isPath(out[0]) && isAbsolute(out[0].toString())) out[0] = toNative(out[0]);
+		if (isPath(out[1])) out[1] = toNative(out[1]);
+		return out;
+	}
+
+	for (let i = 0; i < (pathArgs[base] ?? 0); i++) {
+		const arg = out[i];
+		if (isPath(arg)) out[i] = toNative(arg);
+	}
+	return out;
+}
+
+function mapResult(base: string, result: unknown): unknown {
+	if (returnsPath.has(base) && typeof result == 'string') return fromNative(result);
+
+	// `Dirent.parentPath` is a real path, so it needs to be mapped back too
+	if (base == 'readdir' && Array.isArray(result)) {
+		for (const entry of result) {
+			if (typeof entry?.parentPath == 'string') entry.parentPath = fromNative(entry.parentPath);
+		}
+	}
+
+	// `mkdtempDisposable` returns the path on an object. Disposal uses the path it captured, so this is safe to change.
+	const disposable = result as { path?: unknown };
+	if (base == 'mkdtempDisposable' && typeof disposable?.path == 'string') disposable.path = fromNative(disposable.path);
+
+	return result;
+}
+
+/**
+ * Functions whose last argument is an event listener, not a `(err, result)` callback.
+ * Wrapping those would change the listener's identity, so `unwatchFile` could not remove it.
+ */
+const listenerAPIs = new Set(['watch', 'watchFile', 'unwatchFile']);
+
+/** Translate native paths in errors back into test paths */
+function mapError(error: unknown): unknown {
+	if (!error || typeof error != 'object') return error;
+	const e = error as Record<string, unknown>;
+
+	for (const key of ['path', 'dest'] as const) {
+		if (typeof e[key] == 'string' && e[key].startsWith(root)) e[key] = fromNative(e[key]);
+	}
+	if (typeof e.message == 'string') e.message = e.message.replaceAll(root, '');
+
+	return error;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+function wrap(name: string, fn: Function, promise: boolean): Function {
+	const base = name.endsWith('Sync') ? name.slice(0, -4) : name;
+
+	if (promise) {
+		return async function (...args: unknown[]) {
+			try {
+				return mapResult(base, await fn(...mapArgs(base, args)));
+			} catch (e) {
+				throw mapError(e);
+			}
+		};
+	}
+
+	return function (...args: unknown[]) {
+		const mapped = mapArgs(base, args);
+
+		// Map paths in callback errors and results (e.g. realpath(path, cb))
+		const cb = mapped.at(-1);
+		if (typeof cb == 'function' && !listenerAPIs.has(base)) {
+			mapped[mapped.length - 1] = (err: unknown, result: unknown, ...rest: unknown[]) => cb(mapError(err), mapResult(base, result), ...rest);
+		}
+
+		try {
+			return mapResult(base, fn(...mapped));
+		} catch (e) {
+			throw mapError(e);
+		}
+	};
+}
+
+const wrapped: Record<string, unknown> = {};
+
+for (const [key, value] of Object.entries(native)) {
+	if (key == 'promises') continue;
+	// Classes (Stats, Dirent, ReadStream, ...) must not be wrapped, or `instanceof` breaks
+	wrapped[key] = typeof value == 'function' && !/^[A-Z]/.test(key) ? wrap(key, value, false) : value;
+}
+
+// `using` support, which node:fs does not have (yet?)
+wrapped.watch = function (...args: Parameters<typeof native.watch>) {
+	const watcher = native.watch(...(mapArgs('watch', args) as Parameters<typeof native.watch>));
+	(watcher as any)[Symbol.dispose] ??= () => watcher.close();
+	(watcher as any)[Symbol.asyncDispose] ??= () => watcher.close();
+	return watcher;
+};
+
+const promises: Record<string, unknown> = {};
+
+for (const [key, value] of Object.entries(native.promises)) {
+	promises[key] = typeof value == 'function' && !/^[A-Z]/.test(key) ? wrap(key, value, true) : value;
+}
+
+// promises.watch returns an async iterable, not a promise, so it must not be awaited
+promises.watch = (...args: Parameters<typeof native.promises.watch>) =>
+	native.promises.watch(...(mapArgs('watch', args) as Parameters<typeof native.promises.watch>));
+
+// ZenFS API extension
+promises.exists = (path: PathLike) => Promise.resolve(native.existsSync(toNative(path)));
+
+wrapped.promises = promises;
+
+export const fs = wrapped as unknown as typeof native;
+
+/** So tests can check `stats instanceof Stats` against the correct class */
+export const Stats = native.Stats;
+
+export const flags: Partial<Record<TestFlag, TestFlagState>> = {
+	// Node only implements `lchmod` on macOS
+	lchmod: process.platform == 'darwin',
+	// The suite uses ZenFS' own extended attribute API, which `node:fs` does not have
+	xattr: false,
+};
+
+copySync(data, fs);
+
+// Kill genuinely hung processes without keeping finished ones alive
+setTimeout(() => {
+	console.error(styleText(['yellow', 'bold'], 'Process took longer than 5s and was killed.'));
+	process.exit(255);
+}, 5_000).unref();

package/types/readable-stream.d.ts

@@ -13,6 +13,6 @@ Warning: Do not install @types/readable-stream alongside this package!
 
 /// <reference types="node" preserve="true" />
 declare module 'readable-stream' {
-	import { Readable, Writable } from 'node:stream';
-	export { Readable, Writable };
+	import { finished, Readable, Writable } from 'node:stream';
+	export { finished, Readable, Writable };
 }