@zenfs/core 0.18.0 → 1.0.0-rc.0

package/src/mixins/mutexed.ts

@@ -1,9 +1,9 @@
 import { ErrnoError } from '../error.js';
 import type { File } from '../file.js';
-import type { FileSystem } from '../filesystem.js';
+import type { FileSystem, FileSystemMetadata } from '../filesystem.js';
 import '../polyfills.js';
 import type { Stats } from '../stats.js';
-import type { Mixin } from './shared.js';
+import type { Concrete } from '../utils.js';
 
 export class MutexLock {
 	protected current = Promise.withResolvers<void>();
@@ -13,10 +13,7 @@ export class MutexLock {
 		return this._isLocked;
 	}
 
-	public constructor(
-		public readonly path: string,
-		protected readonly previous?: MutexLock
-	) {}
+	public constructor(protected readonly previous?: MutexLock) {}
 
 	public async done(): Promise<void> {
 		await this.previous?.done();
@@ -34,219 +31,227 @@ export class MutexLock {
 }
 
 /**
- * This serializes access to an underlying async filesystem.
- * For example, on an OverlayFS instance with an async lower
- * directory operations like rename and rmdir may involve multiple
- * requests involving both the upper and lower filesystems -- they
- * are not executed in a single atomic step. OverlayFS uses this
- * to avoid having to reason about the correctness of
- * multiple requests interleaving.
- *
- * Note: `@ts-expect-error 2513` is needed because `FS` is not properly detected as being concrete
- *
- * @todo Change `using _` to `using void` pending https://github.com/tc39/proposal-discard-binding
- * @internal
+ * @hidden
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function Mutexed<T extends new (...args: any[]) => FileSystem>(
-	FS: T
-): Mixin<
-	T,
-	{
-		lock(path: string, syscall: string): Promise<MutexLock>;
-		lockSync(path: string): MutexLock;
-		isLocked(path: string): boolean;
-	}
-> {
-	class MutexedFS extends FS {
-		/**
-		 * The current locks
-		 */
-		private locks: Map<string, MutexLock> = new Map();
-
-		/**
-		 * Adds a lock for a path
-		 */
-		protected addLock(path: string): MutexLock {
-			const previous = this.locks.get(path);
-			const lock = new MutexLock(path, previous?.isLocked ? previous : undefined);
-			this.locks.set(path, lock);
-			return lock;
-		}
+export class __MutexedFS<T extends FileSystem> implements FileSystem {
+	/**
+	 * @internal
+	 */
+	public _fs!: T;
+
+	public async ready(): Promise<void> {
+		return await this._fs.ready();
+	}
 
-		/**
-		 * Locks `path` asynchronously.
-		 * If the path is currently locked, waits for it to be unlocked.
-		 * @internal
-		 */
-		public async lock(path: string, syscall: string): Promise<MutexLock> {
-			const previous = this.locks.get(path);
-			const lock = this.addLock(path);
-			const stack = new Error().stack;
-			setTimeout(() => {
-				if (lock.isLocked) {
-					const error = ErrnoError.With('EDEADLK', path, syscall);
-					error.stack += stack?.slice('Error'.length);
-					throw error;
-				}
-			}, 5000);
-			await previous?.done();
-			return lock;
-		}
+	public metadata(): FileSystemMetadata {
+		return this._fs.metadata();
+	}
 
-		/**
-		 * Locks `path` asynchronously.
-		 * If the path is currently locked, an error will be thrown
-		 * @internal
-		 */
-		public lockSync(path: string): MutexLock {
-			if (this.locks.has(path)) {
-				// Non-null assertion: we already checked locks has path
-				throw ErrnoError.With('EBUSY', path, 'lock');
+	/**
+	 * The current locks
+	 */
+	private currentLock?: MutexLock;
+
+	/**
+	 * Adds a lock for a path
+	 */
+	protected addLock(): MutexLock {
+		const lock = new MutexLock(this.currentLock);
+		this.currentLock = lock;
+		return lock;
+	}
+
+	/**
+	 * Locks `path` asynchronously.
+	 * If the path is currently locked, waits for it to be unlocked.
+	 * @internal
+	 */
+	public async lock(path: string, syscall: string): Promise<MutexLock> {
+		const previous = this.currentLock;
+		const lock = this.addLock();
+		const stack = new Error().stack;
+		setTimeout(() => {
+			if (lock.isLocked) {
+				const error = ErrnoError.With('EDEADLK', path, syscall);
+				error.stack += stack?.slice('Error'.length);
+				throw error;
 			}
+		}, 5000);
+		await previous?.done();
+		return lock;
+	}
 
-			return this.addLock(path);
+	/**
+	 * Locks `path` asynchronously.
+	 * If the path is currently locked, an error will be thrown
+	 * @internal
+	 */
+	public lockSync(path: string, syscall: string): MutexLock {
+		if (this.currentLock) {
+			throw ErrnoError.With('EBUSY', path, syscall);
 		}
 
-		/**
-		 * Whether `path` is locked
-		 * @internal
-		 */
-		public isLocked(path: string): boolean {
-			return !!this.locks.get(path)?.isLocked;
-		}
+		return this.addLock();
+	}
 
-		/* eslint-disable @typescript-eslint/no-unused-vars */
-		public async rename(oldPath: string, newPath: string): Promise<void> {
-			using _ = await this.lock(oldPath, 'rename');
-			// @ts-expect-error 2513
-			await super.rename(oldPath, newPath);
-		}
+	/**
+	 * Whether `path` is locked
+	 * @internal
+	 */
+	public get isLocked(): boolean {
+		return !!this.currentLock?.isLocked;
+	}
 
-		public renameSync(oldPath: string, newPath: string): void {
-			using _ = this.lockSync(oldPath);
-			// @ts-expect-error 2513
-			return super.renameSync(oldPath, newPath);
-		}
+	/* eslint-disable @typescript-eslint/no-unused-vars */
+	public async rename(oldPath: string, newPath: string): Promise<void> {
+		using _ = await this.lock(oldPath, 'rename');
+		await this._fs.rename(oldPath, newPath);
+	}
 
-		public async stat(path: string): Promise<Stats> {
-			using _ = await this.lock(path, 'stat');
-			// @ts-expect-error 2513
-			return await super.stat(path);
-		}
+	public renameSync(oldPath: string, newPath: string): void {
+		using _ = this.lockSync(oldPath, 'rename');
+		return this._fs.renameSync(oldPath, newPath);
+	}
 
-		public statSync(path: string): Stats {
-			using _ = this.lockSync(path);
-			// @ts-expect-error 2513
-			return super.statSync(path);
-		}
+	public async stat(path: string): Promise<Stats> {
+		using _ = await this.lock(path, 'stat');
+		return await this._fs.stat(path);
+	}
 
-		public async openFile(path: string, flag: string): Promise<File> {
-			using _ = await this.lock(path, 'openFile');
-			// @ts-expect-error 2513
-			return await super.openFile(path, flag);
-		}
+	public statSync(path: string): Stats {
+		using _ = this.lockSync(path, 'stat');
+		return this._fs.statSync(path);
+	}
 
-		public openFileSync(path: string, flag: string): File {
-			using _ = this.lockSync(path);
-			// @ts-expect-error 2513
-			return super.openFileSync(path, flag);
-		}
+	public async openFile(path: string, flag: string): Promise<File> {
+		using _ = await this.lock(path, 'openFile');
+		const file = await this._fs.openFile(path, flag);
+		file.fs = this;
+		return file;
+	}
 
-		public async createFile(path: string, flag: string, mode: number): Promise<File> {
-			using _ = await this.lock(path, 'createFile');
-			// @ts-expect-error 2513
-			return await super.createFile(path, flag, mode);
-		}
+	public openFileSync(path: string, flag: string): File {
+		using _ = this.lockSync(path, 'openFile');
+		const file = this._fs.openFileSync(path, flag);
+		file.fs = this;
+		return file;
+	}
 
-		public createFileSync(path: string, flag: string, mode: number): File {
-			using _ = this.lockSync(path);
-			// @ts-expect-error 2513
-			return super.createFileSync(path, flag, mode);
-		}
+	public async createFile(path: string, flag: string, mode: number): Promise<File> {
+		using _ = await this.lock(path, 'createFile');
+		const file = await this._fs.createFile(path, flag, mode);
+		file.fs = this;
+		return file;
+	}
 
-		public async unlink(path: string): Promise<void> {
-			using _ = await this.lock(path, 'unlink');
-			// @ts-expect-error 2513
-			await super.unlink(path);
-		}
+	public createFileSync(path: string, flag: string, mode: number): File {
+		using _ = this.lockSync(path, 'createFile');
+		const file = this._fs.createFileSync(path, flag, mode);
+		file.fs = this;
+		return file;
+	}
 
-		public unlinkSync(path: string): void {
-			using _ = this.lockSync(path);
-			// @ts-expect-error 2513
-			return super.unlinkSync(path);
-		}
+	public async unlink(path: string): Promise<void> {
+		using _ = await this.lock(path, 'unlink');
+		await this._fs.unlink(path);
+	}
 
-		public async rmdir(path: string): Promise<void> {
-			using _ = await this.lock(path, 'rmdir');
-			// @ts-expect-error 2513
-			await super.rmdir(path);
-		}
+	public unlinkSync(path: string): void {
+		using _ = this.lockSync(path, 'unlink');
+		return this._fs.unlinkSync(path);
+	}
 
-		public rmdirSync(path: string): void {
-			using _ = this.lockSync(path);
-			// @ts-expect-error 2513
-			return super.rmdirSync(path);
-		}
+	public async rmdir(path: string): Promise<void> {
+		using _ = await this.lock(path, 'rmdir');
+		await this._fs.rmdir(path);
+	}
 
-		public async mkdir(path: string, mode: number): Promise<void> {
-			using _ = await this.lock(path, 'mkdir');
-			// @ts-expect-error 2513
-			await super.mkdir(path, mode);
-		}
+	public rmdirSync(path: string): void {
+		using _ = this.lockSync(path, 'rmdir');
+		return this._fs.rmdirSync(path);
+	}
 
-		public mkdirSync(path: string, mode: number): void {
-			using _ = this.lockSync(path);
-			// @ts-expect-error 2513
-			return super.mkdirSync(path, mode);
-		}
+	public async mkdir(path: string, mode: number): Promise<void> {
+		using _ = await this.lock(path, 'mkdir');
+		await this._fs.mkdir(path, mode);
+	}
 
-		public async readdir(path: string): Promise<string[]> {
-			using _ = await this.lock(path, 'readdir');
-			// @ts-expect-error 2513
-			return await super.readdir(path);
-		}
+	public mkdirSync(path: string, mode: number): void {
+		using _ = this.lockSync(path, 'mkdir');
+		return this._fs.mkdirSync(path, mode);
+	}
 
-		public readdirSync(path: string): string[] {
-			using _ = this.lockSync(path);
-			// @ts-expect-error 2513
-			return super.readdirSync(path);
-		}
+	public async readdir(path: string): Promise<string[]> {
+		using _ = await this.lock(path, 'readdir');
+		return await this._fs.readdir(path);
+	}
 
-		public async exists(path: string): Promise<boolean> {
-			using _ = await this.lock(path, 'exists');
-			return await super.exists(path);
-		}
+	public readdirSync(path: string): string[] {
+		using _ = this.lockSync(path, 'readdir');
+		return this._fs.readdirSync(path);
+	}
 
-		public existsSync(path: string): boolean {
-			using _ = this.lockSync(path);
-			return super.existsSync(path);
-		}
+	public async exists(path: string): Promise<boolean> {
+		using _ = await this.lock(path, 'exists');
+		return await this._fs.exists(path);
+	}
 
-		public async link(srcpath: string, dstpath: string): Promise<void> {
-			using _ = await this.lock(srcpath, 'link');
-			// @ts-expect-error 2513
-			await super.link(srcpath, dstpath);
-		}
+	public existsSync(path: string): boolean {
+		using _ = this.lockSync(path, 'exists');
+		return this._fs.existsSync(path);
+	}
 
-		public linkSync(srcpath: string, dstpath: string): void {
-			using _ = this.lockSync(srcpath);
-			// @ts-expect-error 2513
-			return super.linkSync(srcpath, dstpath);
-		}
+	public async link(srcpath: string, dstpath: string): Promise<void> {
+		using _ = await this.lock(srcpath, 'link');
+		await this._fs.link(srcpath, dstpath);
+	}
 
-		public async sync(path: string, data: Uint8Array, stats: Readonly<Stats>): Promise<void> {
-			using _ = await this.lock(path, 'sync');
-			// @ts-expect-error 2513
-			await super.sync(path, data, stats);
-		}
+	public linkSync(srcpath: string, dstpath: string): void {
+		using _ = this.lockSync(srcpath, 'link');
+		return this._fs.linkSync(srcpath, dstpath);
+	}
+
+	public async sync(path: string, data: Uint8Array, stats: Readonly<Stats>): Promise<void> {
+		using _ = await this.lock(path, 'sync');
+		await this._fs.sync(path, data, stats);
+	}
+
+	public syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void {
+		using _ = this.lockSync(path, 'sync');
+		return this._fs.syncSync(path, data, stats);
+	}
+	/* eslint-enable @typescript-eslint/no-unused-vars */
+}
 
-		public syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void {
-			using _ = this.lockSync(path);
-			// @ts-expect-error 2513
-			return super.syncSync(path, data, stats);
+/**
+ * This serializes access to an underlying async filesystem.
+ * For example, on an OverlayFS instance with an async lower
+ * directory operations like rename and rmdir may involve multiple
+ * requests involving both the upper and lower filesystems -- they
+ * are not executed in a single atomic step. OverlayFS uses this
+ * to avoid having to reason about the correctness of
+ * multiple requests interleaving.
+ *
+ * Note:
+ * Instead of extending the passed class, `MutexedFS` stores it internally.
+ * This is to avoid a deadlock caused when a mathod calls another one
+ * The problem is discussed extensivly in [#78](https://github.com/zen-fs/core/issues/78)
+ * Instead of extending `FileSystem`,
+ * `MutexedFS` implements it in order to make sure all of the methods are passed through
+ *
+ * @todo Change `using _` to `using void` pending https://github.com/tc39/proposal-discard-binding
+ * @internal
+ */
+export function Mutexed<const T extends Concrete<typeof FileSystem>>(
+	FS: T
+): typeof __MutexedFS<InstanceType<T>> & {
+	new (...args: ConstructorParameters<T>): __MutexedFS<InstanceType<T>>;
+} {
+	class MutexedFS extends __MutexedFS<InstanceType<T>> {
+		public constructor(...args: ConstructorParameters<T>) {
+			super();
+			this._fs = new FS(...args) as InstanceType<T>;
 		}
-		/* eslint-enable @typescript-eslint/no-unused-vars */
 	}
 	return MutexedFS;
 }

package/src/mixins/shared.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
 /*
 	Code shared by various mixins
 */
@@ -9,12 +10,12 @@ import type { FileSystem } from '../filesystem.js';
  * `TBase` with `TMixin` mixed-in.
  * @internal @experimental
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type Mixin<TBase extends typeof FileSystem, TMixin> = (abstract new (...args: any[]) => TMixin) & TBase;
 
 /**
  * Asynchronous `FileSystem` methods. This is a convience type.
  * @internal
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type _AsyncFSMethods = ExtractProperties<FileSystem, (...args: any[]) => Promise<unknown>>;
+
+export type ConcreteFS = ExtractProperties<FileSystem, any>;

package/src/stats.ts

@@ -1,5 +1,5 @@
 import type * as Node from 'fs';
-import type { Credentials } from './credentials.js';
+import { credentials, type Credentials } from './credentials.js';
 import { S_IFBLK, S_IFCHR, S_IFDIR, S_IFIFO, S_IFLNK, S_IFMT, S_IFREG, S_IFSOCK, S_IRWXG, S_IRWXO, S_IRWXU } from './emulation/constants.js';
 import { size_max } from './inode.js';
 
@@ -233,18 +233,17 @@ export abstract class StatsCommon<T extends number | bigint> implements Node.Sta
 	/**
 	 * Checks if a given user/group has access to this item
 	 * @param mode The requested access, combination of W_OK, R_OK, and X_OK
-	 * @param cred The requesting credentials
 	 * @returns True if the request has access, false if the request does not
 	 * @internal
 	 */
-	public hasAccess(mode: number, cred: Credentials): boolean {
-		if (cred.euid === 0 || cred.egid === 0) {
+	public hasAccess(mode: number): boolean {
+		if (credentials.euid === 0 || credentials.egid === 0) {
 			//Running as root
 			return true;
 		}
 
 		// Mask for
-		const adjusted = (cred.uid == this.uid ? S_IRWXU : 0) | (cred.gid == this.gid ? S_IRWXG : 0) | S_IRWXO;
+		const adjusted = (credentials.uid == this.uid ? S_IRWXU : 0) | (credentials.gid == this.gid ? S_IRWXG : 0) | S_IRWXO;
 		return (mode & this.mode & adjusted) == mode;
 	}
 

package/src/utils.ts

@@ -1,6 +1,6 @@
 /* eslint-disable @typescript-eslint/no-unsafe-member-access,@typescript-eslint/no-unsafe-call,@typescript-eslint/no-unsafe-return */
 import type * as fs from 'node:fs';
-import type { OptionalTuple } from 'utilium';
+import type { ClassLike, OptionalTuple } from 'utilium';
 import { dirname, resolve, type AbsolutePath } from './emulation/path.js';
 import { Errno, ErrnoError } from './error.js';
 import type { FileSystem } from './filesystem.js';
@@ -262,3 +262,5 @@ export function normalizeOptions(
 		mode: normalizeMode('mode' in options ? options?.mode : null, mode),
 	};
 }
+
+export type Concrete<T extends ClassLike> = Pick<T, keyof T> & (new (...args: any[]) => InstanceType<T>);