@zenfs/core 0.16.4 → 0.17.0

package/src/backends/{index/fs.ts → file_index.ts}

@@ -1,11 +1,109 @@
-import type { Cred } from '../../cred.js';
-import { ErrnoError, Errno } from '../../error.js';
-import { NoSyncFile, isWriteable, flagToMode } from '../../file.js';
-import { Readonly, FileSystem } from '../../filesystem.js';
-import type { Stats } from '../../stats.js';
-import { decode } from '../../utils.js';
-import type { IndexData } from './index.js';
-import { Index } from './index.js';
+/* Note: this file is named file_index.ts because Typescript has special behavior regarding index.ts which can't be disabled. */
+
+import { isJSON } from 'utilium';
+import type { Cred } from '../cred.js';
+import { basename, dirname } from '../emulation/path.js';
+import { Errno, ErrnoError } from '../error.js';
+import { NoSyncFile, flagToMode, isWriteable } from '../file.js';
+import { FileSystem } from '../filesystem.js';
+import { Readonly } from '../mixins/readonly.js';
+import type { StatsLike } from '../stats.js';
+import { Stats } from '../stats.js';
+import { decode, encode } from '../utils.js';
+
+/**
+ * An Index in JSON form
+ * @internal
+ */
+export interface IndexData {
+	version: 1;
+	entries: Record<string, StatsLike<number>>;
+}
+
+export const version = 1;
+
+/**
+ * An index of files
+ * @internal
+ */
+export class Index extends Map<string, Stats> {
+	/**
+	 * Convience method
+	 */
+	public files(): Map<string, Stats> {
+		const files = new Map<string, Stats>();
+		for (const [path, stats] of this) {
+			if (stats.isFile()) {
+				files.set(path, stats);
+			}
+		}
+		return files;
+	}
+
+	/**
+	 * Converts the index to JSON
+	 */
+	public toJSON(): IndexData {
+		return {
+			version,
+			entries: Object.fromEntries(this),
+		};
+	}
+
+	/**
+	 * Converts the index to a string
+	 */
+	public toString(): string {
+		return JSON.stringify(this.toJSON());
+	}
+
+	/**
+	 * Returns the files in the directory `dir`.
+	 * This is expensive so it is only called once per directory.
+	 */
+	protected dirEntries(dir: string): string[] {
+		const entries = [];
+		for (const entry of this.keys()) {
+			if (dirname(entry) == dir) {
+				entries.push(basename(entry));
+			}
+		}
+		return entries;
+	}
+
+	/**
+	 * Loads the index from JSON data
+	 */
+	public fromJSON(json: IndexData): void {
+		if (json.version != version) {
+			throw new ErrnoError(Errno.EINVAL, 'Index version mismatch');
+		}
+
+		this.clear();
+
+		for (const [path, data] of Object.entries(json.entries)) {
+			const stats = new Stats(data);
+			if (stats.isDirectory()) {
+				stats.fileData = encode(JSON.stringify(this.dirEntries(path)));
+			}
+			this.set(path, stats);
+		}
+	}
+
+	/**
+	 * Parses an index from a string
+	 */
+	public static parse(data: string): Index {
+		if (!isJSON(data)) {
+			throw new ErrnoError(Errno.EINVAL, 'Invalid JSON');
+		}
+
+		const json = JSON.parse(data) as IndexData;
+		const index = new Index();
+		index.fromJSON(json);
+		return index;
+	}
+}
 
 export abstract class IndexFS extends Readonly(FileSystem) {
 	protected index: Index = new Index();

package/src/backends/memory.ts

@@ -26,7 +26,7 @@ export class InMemoryStore extends Map<Ino, Uint8Array> implements SimpleSyncSto
  * A simple in-memory file system backed by an InMemoryStore.
  * Files are not persisted across page loads.
  */
-export const InMemory = {
+export const _InMemory = {
 	name: 'InMemory',
 	isAvailable(): boolean {
 		return true;
@@ -44,3 +44,7 @@ export const InMemory = {
 		return fs;
 	},
 } as const satisfies Backend<StoreFS<InMemoryStore>, { name?: string }>;
+type _inmemory = typeof _InMemory;
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+interface InMemory extends _inmemory {}
+export const InMemory: InMemory = _InMemory;

package/src/backends/overlay.ts

@@ -4,7 +4,7 @@ import { ErrnoError, Errno } from '../error.js';
 import type { File } from '../file.js';
 import { PreloadFile, parseFlag } from '../file.js';
 import { Stats } from '../stats.js';
-import { LockedFS } from './locked.js';
+import { Mutexed } from '../mixins/mutexed.js';
 import { dirname } from '../emulation/path.js';
 import type { Cred } from '../cred.js';
 import { rootCred } from '../cred.js';
@@ -33,19 +33,19 @@ export interface OverlayOptions {
  * OverlayFS makes a read-only filesystem writable by storing writes on a second, writable file system.
  * Deletes are persisted via metadata stored on the writable file system.
  *
- * This class contains no locking whatsoever. It is wrapped in a LockedFS to prevent races.
+ * This class contains no locking whatsoever. It is mutexed to prevent races.
  *
  * @internal
  */
-export class UnlockedOverlayFS extends FileSystem {
+export class UnmutexedOverlayFS extends FileSystem {
 	async ready(): Promise<void> {
-		await this._readable.ready();
-		await this._writable.ready();
+		await this.readable.ready();
+		await this.writable.ready();
 		await this._ready;
 	}
 
-	private _writable: FileSystem;
-	private _readable: FileSystem;
+	public readonly writable: FileSystem;
+	public readonly readable: FileSystem;
 	private _isInitialized: boolean = false;
 	private _deletedFiles: Set<string> = new Set();
 	private _deleteLog: string = '';
@@ -61,9 +61,9 @@ export class UnlockedOverlayFS extends FileSystem {
 
 	constructor({ writable, readable }: OverlayOptions) {
 		super();
-		this._writable = writable;
-		this._readable = readable;
-		if (this._writable.metadata().readonly) {
+		this.writable = writable;
+		this.readable = readable;
+		if (this.writable.metadata().readonly) {
 			throw new ErrnoError(Errno.EINVAL, 'Writable file system must be writable.');
 		}
 		this._ready = this._initialize();
@@ -76,26 +76,19 @@ export class UnlockedOverlayFS extends FileSystem {
 		};
 	}
 
-	public getOverlayedFileSystems(): OverlayOptions {
-		return {
-			readable: this._readable,
-			writable: this._writable,
-		};
-	}
-
 	public async sync(path: string, data: Uint8Array, stats: Readonly<Stats>): Promise<void> {
 		const cred = stats.cred(0, 0);
 		await this.createParentDirectories(path, cred);
-		if (!(await this._writable.exists(path, cred))) {
-			await this._writable.createFile(path, 'w', 0o644, cred);
+		if (!(await this.writable.exists(path, cred))) {
+			await this.writable.createFile(path, 'w', 0o644, cred);
 		}
-		await this._writable.sync(path, data, stats);
+		await this.writable.sync(path, data, stats);
 	}
 
 	public syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void {
 		const cred = stats.cred(0, 0);
 		this.createParentDirectoriesSync(path, cred);
-		this._writable.syncSync(path, data, stats);
+		this.writable.syncSync(path, data, stats);
 	}
 
 	/**
@@ -109,7 +102,7 @@ export class UnlockedOverlayFS extends FileSystem {
 
 		// Read deletion log, process into metadata.
 		try {
-			const file = await this._writable.openFile(deletionLogPath, parseFlag('r'), rootCred);
+			const file = await this.writable.openFile(deletionLogPath, parseFlag('r'), rootCred);
 			const { size } = await file.stat();
 			const { buffer } = await file.read(new Uint8Array(size));
 			this._deleteLog = decode(buffer);
@@ -138,7 +131,7 @@ export class UnlockedOverlayFS extends FileSystem {
 		this.checkPath(newPath);
 
 		try {
-			await this._writable.rename(oldPath, newPath, cred);
+			await this.writable.rename(oldPath, newPath, cred);
 		} catch (e) {
 			if (this._deletedFiles.has(oldPath)) {
 				throw ErrnoError.With('ENOENT', oldPath, 'rename');
@@ -152,7 +145,7 @@ export class UnlockedOverlayFS extends FileSystem {
 		this.checkPath(newPath);
 
 		try {
-			this._writable.renameSync(oldPath, newPath, cred);
+			this.writable.renameSync(oldPath, newPath, cred);
 		} catch (e) {
 			if (this._deletedFiles.has(oldPath)) {
 				throw ErrnoError.With('ENOENT', oldPath, 'rename');
@@ -163,12 +156,12 @@ export class UnlockedOverlayFS extends FileSystem {
 	public async stat(path: string, cred: Cred): Promise<Stats> {
 		this.checkInitialized();
 		try {
-			return await this._writable.stat(path, cred);
+			return await this.writable.stat(path, cred);
 		} catch (e) {
 			if (this._deletedFiles.has(path)) {
 				throw ErrnoError.With('ENOENT', path, 'stat');
 			}
-			const oldStat = new Stats(await this._readable.stat(path, cred));
+			const oldStat = new Stats(await this.readable.stat(path, cred));
 			// Make the oldStat's mode writable. Preserve the topmost part of the mode, which specifies the type
 			oldStat.mode |= 0o222;
 			return oldStat;
@@ -178,12 +171,12 @@ export class UnlockedOverlayFS extends FileSystem {
 	public statSync(path: string, cred: Cred): Stats {
 		this.checkInitialized();
 		try {
-			return this._writable.statSync(path, cred);
+			return this.writable.statSync(path, cred);
 		} catch (e) {
 			if (this._deletedFiles.has(path)) {
 				throw ErrnoError.With('ENOENT', path, 'stat');
 			}
-			const oldStat = new Stats(this._readable.statSync(path, cred));
+			const oldStat = new Stats(this.readable.statSync(path, cred));
 			// Make the oldStat's mode writable. Preserve the topmost part of the mode, which specifies the type.
 			oldStat.mode |= 0o222;
 			return oldStat;
@@ -191,22 +184,22 @@ export class UnlockedOverlayFS extends FileSystem {
 	}
 
 	public async openFile(path: string, flag: string, cred: Cred): Promise<File> {
-		if (await this._writable.exists(path, cred)) {
-			return this._writable.openFile(path, flag, cred);
+		if (await this.writable.exists(path, cred)) {
+			return this.writable.openFile(path, flag, cred);
 		}
 		// Create an OverlayFile.
-		const file = await this._readable.openFile(path, parseFlag('r'), cred);
+		const file = await this.readable.openFile(path, parseFlag('r'), cred);
 		const stats = new Stats(await file.stat());
 		const { buffer } = await file.read(new Uint8Array(stats.size));
 		return new PreloadFile(this, path, flag, stats, buffer);
 	}
 
 	public openFileSync(path: string, flag: string, cred: Cred): File {
-		if (this._writable.existsSync(path, cred)) {
-			return this._writable.openFileSync(path, flag, cred);
+		if (this.writable.existsSync(path, cred)) {
+			return this.writable.openFileSync(path, flag, cred);
 		}
 		// Create an OverlayFile.
-		const file = this._readable.openFileSync(path, parseFlag('r'), cred);
+		const file = this.readable.openFileSync(path, parseFlag('r'), cred);
 		const stats = new Stats(file.statSync());
 		const data = new Uint8Array(stats.size);
 		file.readSync(data);
@@ -215,24 +208,24 @@ export class UnlockedOverlayFS extends FileSystem {
 
 	public async createFile(path: string, flag: string, mode: number, cred: Cred): Promise<File> {
 		this.checkInitialized();
-		await this._writable.createFile(path, flag, mode, cred);
+		await this.writable.createFile(path, flag, mode, cred);
 		return this.openFile(path, flag, cred);
 	}
 
 	public createFileSync(path: string, flag: string, mode: number, cred: Cred): File {
 		this.checkInitialized();
-		this._writable.createFileSync(path, flag, mode, cred);
+		this.writable.createFileSync(path, flag, mode, cred);
 		return this.openFileSync(path, flag, cred);
 	}
 
 	public async link(srcpath: string, dstpath: string, cred: Cred): Promise<void> {
 		this.checkInitialized();
-		await this._writable.link(srcpath, dstpath, cred);
+		await this.writable.link(srcpath, dstpath, cred);
 	}
 
 	public linkSync(srcpath: string, dstpath: string, cred: Cred): void {
 		this.checkInitialized();
-		this._writable.linkSync(srcpath, dstpath, cred);
+		this.writable.linkSync(srcpath, dstpath, cred);
 	}
 
 	public async unlink(path: string, cred: Cred): Promise<void> {
@@ -242,8 +235,8 @@ export class UnlockedOverlayFS extends FileSystem {
 			throw ErrnoError.With('ENOENT', path, 'unlink');
 		}
 
-		if (await this._writable.exists(path, cred)) {
-			await this._writable.unlink(path, cred);
+		if (await this.writable.exists(path, cred)) {
+			await this.writable.unlink(path, cred);
 		}
 
 		// if it still exists add to the delete log
@@ -259,8 +252,8 @@ export class UnlockedOverlayFS extends FileSystem {
 			throw ErrnoError.With('ENOENT', path, 'unlink');
 		}
 
-		if (this._writable.existsSync(path, cred)) {
-			this._writable.unlinkSync(path, cred);
+		if (this.writable.existsSync(path, cred)) {
+			this.writable.unlinkSync(path, cred);
 		}
 
 		// if it still exists add to the delete log
@@ -274,8 +267,8 @@ export class UnlockedOverlayFS extends FileSystem {
 		if (!(await this.exists(path, cred))) {
 			throw ErrnoError.With('ENOENT', path, 'rmdir');
 		}
-		if (await this._writable.exists(path, cred)) {
-			await this._writable.rmdir(path, cred);
+		if (await this.writable.exists(path, cred)) {
+			await this.writable.rmdir(path, cred);
 		}
 		if (await this.exists(path, cred)) {
 			// Check if directory is empty.
@@ -292,8 +285,8 @@ export class UnlockedOverlayFS extends FileSystem {
 		if (!this.existsSync(path, cred)) {
 			throw ErrnoError.With('ENOENT', path, 'rmdir');
 		}
-		if (this._writable.existsSync(path, cred)) {
-			this._writable.rmdirSync(path, cred);
+		if (this.writable.existsSync(path, cred)) {
+			this.writable.rmdirSync(path, cred);
 		}
 		if (this.existsSync(path, cred)) {
 			// Check if directory is empty.
@@ -312,7 +305,7 @@ export class UnlockedOverlayFS extends FileSystem {
 		}
 		// The below will throw should any of the parent directories fail to exist on _writable.
 		await this.createParentDirectories(path, cred);
-		await this._writable.mkdir(path, mode, cred);
+		await this.writable.mkdir(path, mode, cred);
 	}
 
 	public mkdirSync(path: string, mode: number, cred: Cred): void {
@@ -322,7 +315,7 @@ export class UnlockedOverlayFS extends FileSystem {
 		}
 		// The below will throw should any of the parent directories fail to exist on _writable.
 		this.createParentDirectoriesSync(path, cred);
-		this._writable.mkdirSync(path, mode, cred);
+		this.writable.mkdirSync(path, mode, cred);
 	}
 
 	public async readdir(path: string, cred: Cred): Promise<string[]> {
@@ -335,12 +328,12 @@ export class UnlockedOverlayFS extends FileSystem {
 		// Readdir in both, check delete log on RO file system's listing, merge, return.
 		const contents: string[] = [];
 		try {
-			contents.push(...(await this._writable.readdir(path, cred)));
+			contents.push(...(await this.writable.readdir(path, cred)));
 		} catch (e) {
 			// NOP.
 		}
 		try {
-			contents.push(...(await this._readable.readdir(path, cred)).filter((fPath: string) => !this._deletedFiles.has(`${path}/${fPath}`)));
+			contents.push(...(await this.readable.readdir(path, cred)).filter((fPath: string) => !this._deletedFiles.has(`${path}/${fPath}`)));
 		} catch (e) {
 			// NOP.
 		}
@@ -362,12 +355,12 @@ export class UnlockedOverlayFS extends FileSystem {
 		// Readdir in both, check delete log on RO file system's listing, merge, return.
 		let contents: string[] = [];
 		try {
-			contents = contents.concat(this._writable.readdirSync(path, cred));
+			contents = contents.concat(this.writable.readdirSync(path, cred));
 		} catch (e) {
 			// NOP.
 		}
 		try {
-			contents = contents.concat(this._readable.readdirSync(path, cred).filter((fPath: string) => !this._deletedFiles.has(`${path}/${fPath}`)));
+			contents = contents.concat(this.readable.readdirSync(path, cred).filter((fPath: string) => !this._deletedFiles.has(`${path}/${fPath}`)));
 		} catch (e) {
 			// NOP.
 		}
@@ -391,7 +384,7 @@ export class UnlockedOverlayFS extends FileSystem {
 			return;
 		}
 		this._deleteLogUpdatePending = true;
-		const log = await this._writable.openFile(deletionLogPath, parseFlag('w'), cred);
+		const log = await this.writable.openFile(deletionLogPath, parseFlag('w'), cred);
 		try {
 			await log.write(encode(this._deleteLog));
 			if (this._deleteLogUpdateNeeded) {
@@ -445,21 +438,21 @@ export class UnlockedOverlayFS extends FileSystem {
 	private createParentDirectoriesSync(path: string, cred: Cred): void {
 		let parent = dirname(path),
 			toCreate: string[] = [];
-		while (!this._writable.existsSync(parent, cred)) {
+		while (!this.writable.existsSync(parent, cred)) {
 			toCreate.push(parent);
 			parent = dirname(parent);
 		}
 		toCreate = toCreate.reverse();
 
 		for (const p of toCreate) {
-			this._writable.mkdirSync(p, this.statSync(p, cred).mode, cred);
+			this.writable.mkdirSync(p, this.statSync(p, cred).mode, cred);
 		}
 	}
 
 	private async createParentDirectories(path: string, cred: Cred): Promise<void> {
 		let parent = dirname(path),
 			toCreate: string[] = [];
-		while (!(await this._writable.exists(parent, cred))) {
+		while (!(await this.writable.exists(parent, cred))) {
 			toCreate.push(parent);
 			parent = dirname(parent);
 		}
@@ -467,7 +460,7 @@ export class UnlockedOverlayFS extends FileSystem {
 
 		for (const p of toCreate) {
 			const stats = await this.stat(p, cred);
-			await this._writable.mkdir(p, stats.mode, cred);
+			await this.writable.mkdir(p, stats.mode, cred);
 		}
 	}
 
@@ -480,7 +473,7 @@ export class UnlockedOverlayFS extends FileSystem {
 		if (!this.existsSync(path, cred)) {
 			throw ErrnoError.With('ENOENT', path, 'operateOnWriteable');
 		}
-		if (!this._writable.existsSync(path, cred)) {
+		if (!this.writable.existsSync(path, cred)) {
 			// File is on readable storage. Copy to writable storage before
 			// changing its mode.
 			this.copyToWritableSync(path, cred);
@@ -492,7 +485,7 @@ export class UnlockedOverlayFS extends FileSystem {
 			throw ErrnoError.With('ENOENT', path, 'operateOnWritable');
 		}
 
-		if (!(await this._writable.exists(path, cred))) {
+		if (!(await this.writable.exists(path, cred))) {
 			return this.copyToWritable(path, cred);
 		}
 	}
@@ -504,15 +497,15 @@ export class UnlockedOverlayFS extends FileSystem {
 	private copyToWritableSync(path: string, cred: Cred): void {
 		const stats = this.statSync(path, cred);
 		if (stats.isDirectory()) {
-			this._writable.mkdirSync(path, stats.mode, cred);
+			this.writable.mkdirSync(path, stats.mode, cred);
 			return;
 		}
 
 		const data = new Uint8Array(stats.size);
-		const readable = this._readable.openFileSync(path, parseFlag('r'), cred);
+		const readable = this.readable.openFileSync(path, parseFlag('r'), cred);
 		readable.readSync(data);
 		readable.closeSync();
-		const writable = this._writable.openFileSync(path, parseFlag('w'), cred);
+		const writable = this.writable.openFileSync(path, parseFlag('w'), cred);
 		writable.writeSync(data);
 		writable.closeSync();
 	}
@@ -520,15 +513,15 @@ export class UnlockedOverlayFS extends FileSystem {
 	private async copyToWritable(path: string, cred: Cred): Promise<void> {
 		const stats = await this.stat(path, cred);
 		if (stats.isDirectory()) {
-			await this._writable.mkdir(path, stats.mode, cred);
+			await this.writable.mkdir(path, stats.mode, cred);
 			return;
 		}
 
 		const data = new Uint8Array(stats.size);
-		const readable = await this._readable.openFile(path, parseFlag('r'), cred);
+		const readable = await this.readable.openFile(path, parseFlag('r'), cred);
 		await readable.read(data);
 		await readable.close();
-		const writable = await this._writable.openFile(path, parseFlag('w'), cred);
+		const writable = await this.writable.openFile(path, parseFlag('w'), cred);
 		await writable.write(data);
 		await writable.close();
 	}
@@ -540,32 +533,9 @@ export class UnlockedOverlayFS extends FileSystem {
  * file system.
  * @internal
  */
-export class OverlayFS extends LockedFS<UnlockedOverlayFS> {
-	/**
-	 * @param options The options to initialize the OverlayFS with
-	 */
-	constructor(options: OverlayOptions) {
-		super(new UnlockedOverlayFS(options));
-	}
-
-	public getOverlayedFileSystems(): OverlayOptions {
-		return super.fs.getOverlayedFileSystems();
-	}
-
-	public getDeletionLog(): string {
-		return super.fs.getDeletionLog();
-	}
-
-	public resDeletionLog(): string {
-		return super.fs.getDeletionLog();
-	}
-
-	public unwrap(): UnlockedOverlayFS {
-		return super.fs;
-	}
-}
+export class OverlayFS extends Mutexed(UnmutexedOverlayFS) {}
 
-export const Overlay = {
+const _Overlay = {
 	name: 'Overlay',
 
 	options: {
@@ -589,3 +559,7 @@ export const Overlay = {
 		return new OverlayFS(options);
 	},
 } as const satisfies Backend<OverlayFS, OverlayOptions>;
+type _overlay = typeof _Overlay;
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+interface Overlay extends _overlay {}
+export const Overlay: Overlay = _Overlay;

package/src/backends/port/fs.ts

@@ -4,7 +4,8 @@ import type { ExtractProperties } from 'utilium';
 import type { Cred } from '../../cred.js';
 import { Errno, ErrnoError } from '../../error.js';
 import { File } from '../../file.js';
-import { Async, FileSystem, type FileSystemMetadata } from '../../filesystem.js';
+import { FileSystem, type FileSystemMetadata } from '../../filesystem.js';
+import { Async } from '../../mixins/async.js';
 import { Stats, type FileType } from '../../stats.js';
 import { InMemory } from '../memory.js';
 import type { Backend, FilesystemOf } from '../backend.js';
@@ -285,7 +286,7 @@ export function detachFS(port: RPC.Port, fs: FileSystem): void {
 	RPC.detach<FileOrFSRequest>(port, request => handleRequest(port, fs, request));
 }
 
-export const Port = {
+export const _Port = {
 	name: 'Port',
 
 	options: {
@@ -315,6 +316,10 @@ export const Port = {
 		return new PortFS(options);
 	},
 } satisfies Backend<PortFS, RPC.Options>;
+type _port = typeof _Port;
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+interface Port extends _port {}
+export const Port: Port = _Port;
 
 export async function resolveRemoteMount<T extends Backend>(port: RPC.Port, config: MountConfiguration<T>, _depth = 0): Promise<FilesystemOf<T>> {
 	const stopAndReplay = RPC.catchMessages(port);

package/src/backends/{index/readme.md → readme.md}

@@ -1,3 +1,3 @@
-# IndexFS
+## IndexFS
 
 The `IndexFS` class is a base class for other backends that uses an `Index` to store stats for files and directories. The `Index` class inherits from `Map` and stores information about files and directories in a file system.