@zenfs/core 0.9.2 → 0.9.3

package/src/backends/Index.ts

@@ -0,0 +1,500 @@
+import { ApiError, ErrorCode } from '../ApiError.js';
+import type { Cred } from '../cred.js';
+import { basename, dirname, join } from '../emulation/path.js';
+import { NoSyncFile, flagToMode, isWriteable } from '../file.js';
+import { FileSystem, Readonly } from '../filesystem.js';
+import { FileType, Stats } from '../stats.js';
+
+/**
+ * @internal
+ */
+export type ListingTree = { [key: string]: ListingTree | null };
+
+/**
+ * @internal
+ */
+export interface ListingQueueNode<TData> {
+	pwd: string;
+	tree: ListingTree;
+	parent: IndexDirInode<TData>;
+}
+
+/**
+ * A simple class for storing a filesystem index. Assumes that all paths passed
+ * to it are *absolute* paths.
+ *
+ * Can be used as a partial or a full index, although care must be taken if used
+ * for the former purpose, especially when directories are concerned.
+ *
+ * @internal
+ */
+export class FileIndex<TData> {
+	/**
+	 * Static method for constructing indices from a JSON listing.
+	 * @param listing Directory listing generated by tools
+	 * @return A new FileIndex object.
+	 */
+	public static FromListing<T>(listing: ListingTree): FileIndex<T> {
+		const index = new FileIndex<T>();
+		// Add a root DirNode.
+		const rootInode = new IndexDirInode<T>();
+		index._index.set('/', rootInode);
+		const queue: ListingQueueNode<T | Stats>[] = [{ pwd: '', tree: listing, parent: rootInode }];
+		while (queue.length > 0) {
+			let inode: IndexFileInode<Stats> | IndexDirInode<T>;
+			const { tree, pwd, parent } = queue.pop()!;
+			for (const node in tree) {
+				if (!Object.hasOwn(tree, node)) {
+					continue;
+				}
+				const children = tree[node];
+
+				if (children) {
+					const path = pwd + '/' + node;
+					inode = new IndexDirInode<T>();
+					index._index.set(path, inode);
+					queue.push({ pwd: path, tree: children, parent: inode });
+				} else {
+					// This inode doesn't have correct size information, noted with -1.
+					inode = new IndexFileInode<Stats>(new Stats({ mode: FileType.FILE | 0o555 }));
+				}
+				if (!parent) {
+					continue;
+				}
+				parent._listing.set(node, inode);
+			}
+		}
+		return index;
+	}
+
+	// Maps directory paths to directory inodes, which contain files.
+	protected _index: Map<string, IndexDirInode<TData>> = new Map();
+
+	/**
+	 * Constructs a new FileIndex.
+	 */
+	constructor() {
+		// _index is a single-level key,value store that maps *directory* paths to
+		// DirInodes. File information is only contained in DirInodes themselves.
+		// Create the root directory.
+		this.add('/', new IndexDirInode());
+	}
+
+	public files(): IndexFileInode<TData>[] {
+		const files: IndexFileInode<TData>[] = [];
+
+		for (const dir of this._index.values()) {
+			for (const file of dir.listing) {
+				const item = dir.get(file);
+				if (!item?.isFile()) {
+					continue;
+				}
+
+				files.push(item);
+			}
+		}
+		return files;
+	}
+
+	/**
+	 * Adds the given absolute path to the index if it is not already in the index.
+	 * Creates any needed parent directories.
+	 * @param path The path to add to the index.
+	 * @param inode The inode for the
+	 *   path to add.
+	 * @return 'True' if it was added or already exists, 'false' if there
+	 *   was an issue adding it (e.g. item in path is a file, item exists but is
+	 *   different).
+	 * @todo If adding fails and implicitly creates directories, we do not clean up
+	 *   the new empty directories.
+	 */
+	public add(path: string, inode: IndexInode<TData>): boolean {
+		if (!inode) {
+			throw new Error('Inode must be specified');
+		}
+		if (!path.startsWith('/')) {
+			throw new Error('Path must be absolute, got: ' + path);
+		}
+
+		// Check if it already exists.
+		if (this._index.has(path)) {
+			return this._index.get(path) === inode;
+		}
+
+		const dirpath = dirname(path);
+
+		// Try to add to its parent directory first.
+		let parent = this._index.get(dirpath);
+		if (!parent && path != '/') {
+			// Create parent.
+			parent = new IndexDirInode<TData>();
+			if (!this.add(dirpath, parent)) {
+				return false;
+			}
+		}
+
+		// Add to parent.
+		if (path != '/' && !parent.add(basename(path), inode)) {
+			return false;
+		}
+
+		// If a directory, add to the index.
+		if (inode.isDirectory()) {
+			this._index.set(path, inode);
+		}
+		return true;
+	}
+
+	/**
+	 * Adds the given absolute path to the index if it is not already in the index.
+	 * The path is added without special treatment (no joining of adjacent separators, etc).
+	 * Creates any needed parent directories.
+	 * @param path The path to add to the index.
+	 * @param inode The inode for the path to add.
+	 * @return 'True' if it was added or already exists, 'false' if there
+	 *   was an issue adding it (e.g. item in path is a file, item exists but is
+	 *   different).
+	 * @todo If adding fails and implicitly creates directories, we do not clean up the new empty directories.
+	 */
+	public addFast(path: string, inode: IndexInode<TData>): boolean {
+		const parentPath = dirname(path);
+		const itemName = basename(path);
+
+		// Try to add to its parent directory first.
+		let parent = this._index.get(parentPath);
+		if (!parent) {
+			// Create parent.
+			parent = new IndexDirInode<TData>();
+			this.addFast(parentPath, parent);
+		}
+
+		if (!parent.add(itemName, inode)) {
+			return false;
+		}
+
+		// If adding a directory, add to the index as well.
+		if (inode.isDirectory()) {
+			this._index.set(path, <IndexDirInode<TData>>inode);
+		}
+		return true;
+	}
+
+	/**
+	 * Removes the given path. Can be a file or a directory.
+	 * @return The removed item,
+	 *   or null if it did not exist.
+	 */
+	public remove(path: string): IndexInode<TData> | null {
+		const dirpath = dirname(path);
+
+		// Try to remove it from its parent directory first.
+		const parent = this._index.get(dirpath);
+		if (!parent) {
+			return;
+		}
+		// Remove from parent.
+		const inode = parent.remove(basename(path));
+		if (!inode) {
+			return;
+		}
+
+		if (!inode.isDirectory()) {
+			return inode;
+		}
+		// If a directory, remove from the index, and remove children.
+		const children = inode.listing;
+		for (const child of children) {
+			this.remove(join(path, child));
+		}
+
+		// Remove the directory from the index, unless it's the root.
+		if (path != '/') {
+			this._index.delete(path);
+		}
+	}
+
+	/**
+	 * Retrieves the directory listing of the given path.
+	 * @return An array of files in the given path, or 'null' if it does not exist.
+	 */
+	public ls(path: string): string[] | null {
+		return this._index.get(path)?.listing;
+	}
+
+	/**
+	 * Returns the inode of the given item.
+	 * @return Returns null if the item does not exist.
+	 */
+	public get(path: string): IndexInode<TData> | null {
+		const dirpath = dirname(path);
+
+		// Retrieve from its parent directory.
+		const parent = this._index.get(dirpath);
+		// Root case
+		if (dirpath == path) {
+			return parent;
+		}
+		return parent?.get(basename(path));
+	}
+}
+
+/**
+ * Generic interface for file/directory inodes.
+ * Note that Stats objects are what we use for file inodes.
+ */
+export abstract class IndexInode<TData> {
+	constructor(public data?: TData) {}
+	/**
+	 * Whether this inode is for a file
+	 */
+	abstract isFile(): this is IndexFileInode<TData>;
+	/**
+	 * Whether this inode is for a directory
+	 */
+	abstract isDirectory(): this is IndexDirInode<TData>;
+
+	abstract toStats(): Stats;
+}
+
+/**
+ * Inode for a file. Stores an arbitrary (filesystem-specific) data payload.
+ */
+export class IndexFileInode<TData> extends IndexInode<TData> {
+	public isFile() {
+		return true;
+	}
+	public isDirectory() {
+		return false;
+	}
+
+	public toStats(): Stats {
+		return new Stats({ mode: FileType.FILE | 0o666, size: 4096 });
+	}
+}
+
+/**
+ * Inode for a directory. Currently only contains the directory listing.
+ */
+export class IndexDirInode<TData> extends IndexInode<TData> {
+	/**
+	 * @internal
+	 */
+	_listing: Map<string, IndexInode<TData>> = new Map();
+
+	public isFile(): boolean {
+		return false;
+	}
+
+	public isDirectory(): boolean {
+		return true;
+	}
+
+	/**
+	 * Return a Stats object for this inode.
+	 * @todo Should probably remove this at some point. This isn't the responsibility of the FileIndex.
+	 */
+	public get stats(): Stats {
+		return new Stats({ mode: FileType.DIRECTORY | 0o555, size: 4096 });
+	}
+	/**
+	 * Alias of getStats()
+	 * @todo Remove this at some point. This isn't the responsibility of the FileIndex.
+	 */
+	public toStats(): Stats {
+		return this.stats;
+	}
+	/**
+	 * Returns the directory listing for this directory. Paths in the directory are
+	 * relative to the directory's path.
+	 * @return The directory listing for this directory.
+	 */
+	public get listing(): string[] {
+		return [...this._listing.keys()];
+	}
+
+	/**
+	 * Returns the inode for the indicated item, or null if it does not exist.
+	 * @param path Name of item in this directory.
+	 */
+	public get(path: string): IndexInode<TData> | null {
+		return this._listing.get(path);
+	}
+	/**
+	 * Add the given item to the directory listing. Note that the given inode is
+	 * not copied, and will be mutated by the DirInode if it is a DirInode.
+	 * @param path Item name to add to the directory listing.
+	 * @param inode The inode for the
+	 *   item to add to the directory inode.
+	 * @return True if it was added, false if it already existed.
+	 */
+	public add(path: string, inode: IndexInode<TData>): boolean {
+		if (this._listing.has(path)) {
+			return false;
+		}
+		this._listing.set(path, inode);
+		return true;
+	}
+	/**
+	 * Removes the given item from the directory listing.
+	 * @param p Name of item to remove from the directory listing.
+	 * @return Returns the item
+	 *   removed, or null if the item did not exist.
+	 */
+	public remove(p: string): IndexInode<TData> | null {
+		const item = this._listing.get(p);
+		if (!item) {
+			return;
+		}
+		this._listing.delete(p);
+		return item;
+	}
+}
+
+export abstract class IndexFS<TData> extends Readonly(FileSystem) {
+	protected _index: FileIndex<TData>;
+
+	constructor(index: ListingTree) {
+		super();
+		this._index = FileIndex.FromListing<TData>(index);
+	}
+
+	public async stat(path: string): Promise<Stats> {
+		const inode = this._index.get(path);
+		if (!inode) {
+			throw ApiError.With('ENOENT', path, 'stat');
+		}
+
+		if (inode.isDirectory()) {
+			return inode.stats;
+		}
+
+		if (inode.isFile()) {
+			return this.statFileInode(inode, path);
+		}
+
+		throw new ApiError(ErrorCode.EINVAL, 'Invalid inode.');
+	}
+
+	public statSync(path: string): Stats {
+		const inode = this._index.get(path);
+		if (!inode) {
+			throw ApiError.With('ENOENT', path, 'stat');
+		}
+
+		if (inode.isDirectory()) {
+			return inode.stats;
+		}
+
+		if (inode.isFile()) {
+			return this.statFileInodeSync(inode, path);
+		}
+
+		throw new ApiError(ErrorCode.EINVAL, 'Invalid inode.');
+	}
+
+	public async openFile(path: string, flag: string, cred: Cred): Promise<NoSyncFile<this>> {
+		if (isWriteable(flag)) {
+			// You can't write to files on this file system.
+			throw new ApiError(ErrorCode.EPERM, path);
+		}
+
+		// Check if the path exists, and is a file.
+		const inode = this._index.get(path);
+
+		if (!inode) {
+			throw ApiError.With('ENOENT', path, 'openFile');
+		}
+
+		if (!inode.toStats().hasAccess(flagToMode(flag), cred)) {
+			throw ApiError.With('EACCES', path, 'openFile');
+		}
+
+		if (inode.isDirectory()) {
+			const stats = inode.stats;
+			return new NoSyncFile(this, path, flag, stats, stats.fileData);
+		}
+
+		return this.openFileInode(inode, path, flag);
+	}
+
+	public openFileSync(path: string, flag: string, cred: Cred): NoSyncFile<this> {
+		if (isWriteable(flag)) {
+			// You can't write to files on this file system.
+			throw new ApiError(ErrorCode.EPERM, path);
+		}
+
+		// Check if the path exists, and is a file.
+		const inode = this._index.get(path);
+
+		if (!inode) {
+			throw ApiError.With('ENOENT', path, 'openFile');
+		}
+
+		if (!inode.toStats().hasAccess(flagToMode(flag), cred)) {
+			throw ApiError.With('EACCES', path, 'openFile');
+		}
+
+		if (inode.isDirectory()) {
+			const stats = inode.stats;
+			return new NoSyncFile(this, path, flag, stats, stats.fileData);
+		}
+
+		return this.openFileInodeSync(inode, path, flag);
+	}
+
+	public async readdir(path: string): Promise<string[]> {
+		// Check if it exists.
+		const inode = this._index.get(path);
+		if (!inode) {
+			throw ApiError.With('ENOENT', path, 'readdir');
+		}
+
+		if (inode.isDirectory()) {
+			return inode.listing;
+		}
+
+		throw ApiError.With('ENOTDIR', path, 'readdir');
+	}
+
+	public readdirSync(path: string): string[] {
+		// Check if it exists.
+		const inode = this._index.get(path);
+		if (!inode) {
+			throw ApiError.With('ENOENT', path, 'readdir');
+		}
+
+		if (inode.isDirectory()) {
+			return inode.listing;
+		}
+
+		throw ApiError.With('ENOTDIR', path, 'readdir');
+	}
+
+	protected abstract statFileInode(inode: IndexFileInode<TData>, path: string): Promise<Stats>;
+
+	protected abstract statFileInodeSync(inode: IndexFileInode<TData>, path: string): Stats;
+
+	protected abstract openFileInode(inode: IndexFileInode<TData>, path: string, flag: string): Promise<NoSyncFile<this>>;
+
+	protected abstract openFileInodeSync(inode: IndexFileInode<TData>, path: string, flag: string): NoSyncFile<this>;
+}
+
+export abstract class SyncIndexFS<TData> extends IndexFS<TData> {
+	protected async statFileInode(inode: IndexFileInode<TData>, path: string): Promise<Stats> {
+		return this.statFileInodeSync(inode, path);
+	}
+
+	protected async openFileInode(inode: IndexFileInode<TData>, path: string, flag: string): Promise<NoSyncFile<this>> {
+		return this.openFileInodeSync(inode, path, flag);
+	}
+}
+
+export abstract class AsyncIndexFS<TData> extends IndexFS<TData> {
+	protected statFileInodeSync(inode: IndexFileInode<TData>, path: string): Stats {
+		throw ApiError.With('ENOSYS', path, 'AsyncIndexFS.statFileInodeSync');
+	}
+
+	protected openFileInodeSync(inode: IndexFileInode<TData>, path: string, flag: string): NoSyncFile<this> {
+		throw ApiError.With('ENOSYS', path, 'AsyncIndexFS.openFileInodeSync');
+	}
+}

package/src/backends/Locked.ts

@@ -0,0 +1,181 @@
+import type { Cred } from '../cred.js';
+import type { File } from '../file.js';
+import type { FileSystem, FileSystemMetadata } from '../filesystem.js';
+import { Mutex } from '../mutex.js';
+import type { Stats } from '../stats.js';
+
+/**
+ * This class 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
+ * LockedFS to avoid having to reason about the correctness of
+ * multiple requests interleaving.
+ * @internal
+ */
+export class LockedFS<FS extends FileSystem> implements FileSystem {
+	private _mu: Mutex = new Mutex();
+
+	constructor(public readonly fs: FS) {}
+
+	public async ready(): Promise<this> {
+		await this.fs.ready();
+		return this;
+	}
+
+	public metadata(): FileSystemMetadata {
+		return {
+			...this.fs.metadata(),
+			name: 'Locked<' + this.fs.metadata().name + '>',
+		};
+	}
+
+	public async rename(oldPath: string, newPath: string, cred: Cred): Promise<void> {
+		await this._mu.lock(oldPath);
+		await this.fs.rename(oldPath, newPath, cred);
+		this._mu.unlock(oldPath);
+	}
+
+	public renameSync(oldPath: string, newPath: string, cred: Cred): void {
+		if (this._mu.isLocked(oldPath)) {
+			throw new Error('invalid sync call');
+		}
+		return this.fs.renameSync(oldPath, newPath, cred);
+	}
+
+	public async stat(p: string, cred: Cred): Promise<Stats> {
+		await this._mu.lock(p);
+		const stats = await this.fs.stat(p, cred);
+		this._mu.unlock(p);
+		return stats;
+	}
+
+	public statSync(p: string, cred: Cred): Stats {
+		if (this._mu.isLocked(p)) {
+			throw new Error('invalid sync call');
+		}
+		return this.fs.statSync(p, cred);
+	}
+
+	public async openFile(path: string, flag: string, cred: Cred): Promise<File> {
+		await this._mu.lock(path);
+		const fd = await this.fs.openFile(path, flag, cred);
+		this._mu.unlock(path);
+		return fd;
+	}
+
+	public openFileSync(path: string, flag: string, cred: Cred): File {
+		if (this._mu.isLocked(path)) {
+			throw new Error('invalid sync call');
+		}
+		return this.fs.openFileSync(path, flag, cred);
+	}
+
+	public async createFile(path: string, flag: string, mode: number, cred: Cred): Promise<File> {
+		await this._mu.lock(path);
+		const fd = await this.fs.createFile(path, flag, mode, cred);
+		this._mu.unlock(path);
+		return fd;
+	}
+
+	public createFileSync(path: string, flag: string, mode: number, cred: Cred): File {
+		if (this._mu.isLocked(path)) {
+			throw new Error('invalid sync call');
+		}
+		return this.fs.createFileSync(path, flag, mode, cred);
+	}
+
+	public async unlink(p: string, cred: Cred): Promise<void> {
+		await this._mu.lock(p);
+		await this.fs.unlink(p, cred);
+		this._mu.unlock(p);
+	}
+
+	public unlinkSync(p: string, cred: Cred): void {
+		if (this._mu.isLocked(p)) {
+			throw new Error('invalid sync call');
+		}
+		return this.fs.unlinkSync(p, cred);
+	}
+
+	public async rmdir(p: string, cred: Cred): Promise<void> {
+		await this._mu.lock(p);
+		await this.fs.rmdir(p, cred);
+		this._mu.unlock(p);
+	}
+
+	public rmdirSync(p: string, cred: Cred): void {
+		if (this._mu.isLocked(p)) {
+			throw new Error('invalid sync call');
+		}
+		return this.fs.rmdirSync(p, cred);
+	}
+
+	public async mkdir(p: string, mode: number, cred: Cred): Promise<void> {
+		await this._mu.lock(p);
+		await this.fs.mkdir(p, mode, cred);
+		this._mu.unlock(p);
+	}
+
+	public mkdirSync(p: string, mode: number, cred: Cred): void {
+		if (this._mu.isLocked(p)) {
+			throw new Error('invalid sync call');
+		}
+		return this.fs.mkdirSync(p, mode, cred);
+	}
+
+	public async readdir(p: string, cred: Cred): Promise<string[]> {
+		await this._mu.lock(p);
+		const files = await this.fs.readdir(p, cred);
+		this._mu.unlock(p);
+		return files;
+	}
+
+	public readdirSync(p: string, cred: Cred): string[] {
+		if (this._mu.isLocked(p)) {
+			throw new Error('invalid sync call');
+		}
+		return this.fs.readdirSync(p, cred);
+	}
+
+	public async exists(p: string, cred: Cred): Promise<boolean> {
+		await this._mu.lock(p);
+		const exists = await this.fs.exists(p, cred);
+		this._mu.unlock(p);
+		return exists;
+	}
+
+	public existsSync(p: string, cred: Cred): boolean {
+		if (this._mu.isLocked(p)) {
+			throw new Error('invalid sync call');
+		}
+		return this.fs.existsSync(p, cred);
+	}
+
+	public async link(srcpath: string, dstpath: string, cred: Cred): Promise<void> {
+		await this._mu.lock(srcpath);
+		await this.fs.link(srcpath, dstpath, cred);
+		this._mu.unlock(srcpath);
+	}
+
+	public linkSync(srcpath: string, dstpath: string, cred: Cred): void {
+		if (this._mu.isLocked(srcpath)) {
+			throw new Error('invalid sync call');
+		}
+		return this.fs.linkSync(srcpath, dstpath, cred);
+	}
+
+	public async sync(path: string, data: Uint8Array, stats: Readonly<Stats>): Promise<void> {
+		await this._mu.lock(path);
+		await this.fs.sync(path, data, stats);
+		this._mu.unlock(path);
+	}
+
+	public syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void {
+		if (this._mu.isLocked(path)) {
+			throw new Error('invalid sync call');
+		}
+		return this.fs.syncSync(path, data, stats);
+	}
+}