@zenfs/core 0.9.6 → 0.10.0

package/src/backends/Fetch.ts

@@ -0,0 +1,230 @@
+import { ErrnoError, Errno } from '../error.js';
+import { NoSyncFile } from '../file.js';
+import type { FileSystemMetadata } from '../filesystem.js';
+import { Stats } from '../stats.js';
+import { type ListingTree, FileIndex, type IndexFileInode, AsyncIndexFS } from './Index.js';
+import type { Backend } from './backend.js';
+
+/**
+ * @hidden
+ */
+function convertError(e: Error): never {
+	throw new ErrnoError(Errno.EIO, e.message);
+}
+
+/**
+ * Asynchronously download a file as a buffer or a JSON object.
+ * Note that the third function signature with a non-specialized type is
+ * invalid, but TypeScript requires it when you specialize string arguments to
+ * constants.
+ * @hidden
+ */
+async function fetchFile(p: string, type: 'buffer'): Promise<Uint8Array>;
+async function fetchFile<T extends object>(p: string, type: 'json'): Promise<T>;
+async function fetchFile<T extends object>(p: string, type: 'buffer' | 'json'): Promise<T | Uint8Array>;
+async function fetchFile<T extends object>(p: string, type: 'buffer' | 'json'): Promise<T | Uint8Array> {
+	const response = await fetch(p).catch(convertError);
+	if (!response.ok) {
+		throw new ErrnoError(Errno.EIO, 'fetch failed: response returned code ' + response.status);
+	}
+	switch (type) {
+		case 'buffer':
+			const arrayBuffer = await response.arrayBuffer().catch(convertError);
+			return new Uint8Array(arrayBuffer);
+		case 'json':
+			return response.json().catch(convertError) as Promise<T>;
+		default:
+			throw new ErrnoError(Errno.EINVAL, 'Invalid download type: ' + type);
+	}
+}
+
+/**
+ * Asynchronously retrieves the size of the given file in bytes.
+ * @hidden
+ */
+async function fetchSize(p: string): Promise<number> {
+	const response = await fetch(p, { method: 'HEAD' }).catch(convertError);
+	if (!response.ok) {
+		throw new ErrnoError(Errno.EIO, 'fetch failed: HEAD response returned code ' + response.status);
+	}
+	return parseInt(response.headers.get('Content-Length') || '-1', 10);
+}
+
+/**
+ * Configuration options for FetchFS.
+ */
+export interface FetchOptions {
+	/**
+	 * URL to a file index as a JSON file or the file index object itself.
+	 * Defaults to `index.json`.
+	 */
+	index?: string | ListingTree;
+
+	/** Used as the URL prefix for fetched files.
+	 * Default: Fetch files relative to the index.
+	 */
+	baseUrl?: string;
+}
+
+/**
+ * A simple filesystem backed by HTTP using the fetch API.
+ *
+ *
+ * Listings objects look like the following:
+ *
+ * ```json
+ * {
+ *   "home": {
+ *     "jvilk": {
+ *       "someFile.txt": null,
+ *       "someDir": {
+ *         // Empty directory
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * This example has the folder `/home/jvilk` with subfile `someFile.txt` and subfolder `someDir`.
+ */
+export class FetchFS extends AsyncIndexFS<Stats> {
+	public readonly prefixUrl: string;
+
+	protected _init: Promise<void>;
+
+	protected async _initialize(index: string | ListingTree): Promise<void> {
+		if (typeof index != 'string') {
+			this._index = FileIndex.FromListing(index);
+			return;
+		}
+
+		try {
+			const response = await fetch(index);
+			this._index = FileIndex.FromListing((await response.json()) as ListingTree);
+		} catch (e) {
+			throw new ErrnoError(Errno.EINVAL, 'Invalid or unavailable file listing tree');
+		}
+	}
+
+	public async ready(): Promise<this> {
+		await this._init;
+		return this;
+	}
+
+	constructor({ index = 'index.json', baseUrl = '' }: FetchOptions) {
+		super({});
+
+		// prefix url must end in a directory separator.
+		if (baseUrl.at(-1) != '/') {
+			baseUrl += '/';
+		}
+		this.prefixUrl = baseUrl;
+
+		this._init = this._initialize(index);
+	}
+
+	public metadata(): FileSystemMetadata {
+		return {
+			...super.metadata(),
+			name: FetchFS.name,
+			readonly: true,
+		};
+	}
+
+	public empty(): void {
+		for (const file of this._index.files()) {
+			delete file.data!.fileData;
+		}
+	}
+
+	/**
+	 * Special function: Preload the given file into the index.
+	 * @param path
+	 * @param buffer
+	 */
+	public preloadFile(path: string, buffer: Uint8Array): void {
+		const inode = this._index.get(path)!;
+		if (!inode) {
+			throw ErrnoError.With('ENOENT', path, 'preloadFile');
+		}
+		if (!inode.isFile()) {
+			throw ErrnoError.With('EISDIR', path, 'preloadFile');
+		}
+		const stats = inode.data!;
+		stats.size = buffer.length;
+		stats.fileData = buffer;
+	}
+
+	protected async statFileInode(inode: IndexFileInode<Stats>, path: string): Promise<Stats> {
+		const stats = inode.data!;
+		// At this point, a non-opened file will still have default stats from the listing.
+		if (stats.size < 0) {
+			stats.size = await this._fetchSize(path);
+		}
+
+		return stats;
+	}
+
+	protected async openFileInode(inode: IndexFileInode<Stats>, path: string, flag: string): Promise<NoSyncFile<this>> {
+		const stats = inode.data!;
+		// Use existing file contents. This maintains the previously-used flag.
+		if (stats.fileData) {
+			return new NoSyncFile(this, path, flag, new Stats(stats), stats.fileData);
+		}
+		// @todo be lazier about actually requesting the file
+		const data = await this._fetchFile(path, 'buffer');
+		// we don't initially have file sizes
+		stats.size = data.length;
+		stats.fileData = data;
+		return new NoSyncFile(this, path, flag, new Stats(stats), data);
+	}
+
+	private _getRemotePath(filePath: string): string {
+		if (filePath.charAt(0) === '/') {
+			filePath = filePath.slice(1);
+		}
+		return this.prefixUrl + filePath;
+	}
+
+	/**
+	 * Asynchronously download the given file.
+	 */
+	protected _fetchFile(p: string, type: 'buffer'): Promise<Uint8Array>;
+	protected _fetchFile(p: string, type: 'json'): Promise<object>;
+	protected _fetchFile(p: string, type: 'buffer' | 'json'): Promise<object>;
+	protected _fetchFile(p: string, type: 'buffer' | 'json'): Promise<object> {
+		return fetchFile(this._getRemotePath(p), type);
+	}
+
+	/**
+	 * Only requests the HEAD content, for the file size.
+	 */
+	protected _fetchSize(path: string): Promise<number> {
+		return fetchSize(this._getRemotePath(path));
+	}
+}
+
+export const Fetch = {
+	name: 'Fetch',
+
+	options: {
+		index: {
+			type: ['string', 'object'],
+			required: false,
+			description: 'URL to a file index as a JSON file or the file index object itself, generated with the make_http_index script. Defaults to `index.json`.',
+		},
+		baseUrl: {
+			type: 'string',
+			required: false,
+			description: 'Used as the URL prefix for fetched files. Default: Fetch files relative to the index.',
+		},
+	},
+
+	isAvailable(): boolean {
+		return typeof globalThis.fetch == 'function';
+	},
+
+	create(options: FetchOptions) {
+		return new FetchFS(options);
+	},
+} as const satisfies Backend<FetchFS, FetchOptions>;

package/src/backends/Index.ts

@@ -1,4 +1,4 @@
-import { ApiError, ErrorCode } from '../ApiError.js';
+import { ErrnoError, Errno } from '../error.js';
 import type { Cred } from '../cred.js';
 import { basename, dirname, join } from '../emulation/path.js';
 import { NoSyncFile, flagToMode, isWriteable } from '../file.js';
@@ -86,7 +86,10 @@ export class FileIndex<TData> {
 		for (const dir of this._index.values()) {
 			for (const file of dir.listing) {
 				const item = dir.get(file);
-				if (!item?.isFile()) {
+				if (!item) {
+					continue;
+				}
+				if (!item.isFile()) {
 					continue;
 				}
 
@@ -110,10 +113,10 @@ export class FileIndex<TData> {
 	 */
 	public add(path: string, inode: IndexInode<TData>): boolean {
 		if (!inode) {
-			throw new Error('Inode must be specified');
+			throw new ErrnoError(Errno.EINVAL, 'Inode must be specified', path, 'FileIndex.add');
 		}
 		if (!path.startsWith('/')) {
-			throw new Error('Path must be absolute, got: ' + path);
+			throw new ErrnoError(Errno.EINVAL, 'Path not absolute', path, 'FileIndex.add');
 		}
 
 		// Check if it already exists.
@@ -123,11 +126,12 @@ export class FileIndex<TData> {
 
 		const dirpath = dirname(path);
 
+		const hasParent = this._index.has(dirpath);
+
+		const parent = hasParent ? this._index.get(dirpath)! : new IndexDirInode<TData>();
+
 		// Try to add to its parent directory first.
-		let parent = this._index.get(dirpath);
-		if (!parent && path != '/') {
-			// Create parent.
-			parent = new IndexDirInode<TData>();
+		if (!hasParent && path != '/') {
 			if (!this.add(dirpath, parent)) {
 				return false;
 			}
@@ -184,7 +188,7 @@ export class FileIndex<TData> {
 	 * @return The removed item,
 	 *   or null if it did not exist.
 	 */
-	public remove(path: string): IndexInode<TData> | null {
+	public remove(path: string): IndexInode<TData> | void {
 		const dirpath = dirname(path);
 
 		// Try to remove it from its parent directory first.
@@ -217,7 +221,7 @@ export class FileIndex<TData> {
 	 * 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 {
+	public ls(path: string): string[] | void {
 		return this._index.get(path)?.listing;
 	}
 
@@ -225,7 +229,7 @@ export class FileIndex<TData> {
 	 * Returns the inode of the given item.
 	 * @return Returns null if the item does not exist.
 	 */
-	public get(path: string): IndexInode<TData> | null {
+	public get(path: string): IndexInode<TData> | void | null {
 		const dirpath = dirname(path);
 
 		// Retrieve from its parent directory.
@@ -316,7 +320,7 @@ export class IndexDirInode<TData> extends IndexInode<TData> {
 	 * 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 {
+	public get(path: string): IndexInode<TData> | void {
 		return this._listing.get(path);
 	}
 	/**
@@ -340,7 +344,7 @@ export class IndexDirInode<TData> extends IndexInode<TData> {
 	 * @return Returns the item
 	 *   removed, or null if the item did not exist.
 	 */
-	public remove(p: string): IndexInode<TData> | null {
+	public remove(p: string): IndexInode<TData> | void {
 		const item = this._listing.get(p);
 		if (!item) {
 			return;
@@ -361,7 +365,7 @@ export abstract class IndexFS<TData> extends Readonly(FileSystem) {
 	public async stat(path: string): Promise<Stats> {
 		const inode = this._index.get(path);
 		if (!inode) {
-			throw ApiError.With('ENOENT', path, 'stat');
+			throw ErrnoError.With('ENOENT', path, 'stat');
 		}
 
 		if (inode.isDirectory()) {
@@ -372,13 +376,13 @@ export abstract class IndexFS<TData> extends Readonly(FileSystem) {
 			return this.statFileInode(inode, path);
 		}
 
-		throw new ApiError(ErrorCode.EINVAL, 'Invalid inode.');
+		throw new ErrnoError(Errno.EINVAL, 'Invalid inode.');
 	}
 
 	public statSync(path: string): Stats {
 		const inode = this._index.get(path);
 		if (!inode) {
-			throw ApiError.With('ENOENT', path, 'stat');
+			throw ErrnoError.With('ENOENT', path, 'stat');
 		}
 
 		if (inode.isDirectory()) {
@@ -389,24 +393,24 @@ export abstract class IndexFS<TData> extends Readonly(FileSystem) {
 			return this.statFileInodeSync(inode, path);
 		}
 
-		throw new ApiError(ErrorCode.EINVAL, 'Invalid inode.');
+		throw new ErrnoError(Errno.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);
+			throw new ErrnoError(Errno.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');
+			throw ErrnoError.With('ENOENT', path, 'openFile');
 		}
 
 		if (!inode.toStats().hasAccess(flagToMode(flag), cred)) {
-			throw ApiError.With('EACCES', path, 'openFile');
+			throw ErrnoError.With('EACCES', path, 'openFile');
 		}
 
 		if (inode.isDirectory()) {
@@ -420,18 +424,18 @@ export abstract class IndexFS<TData> extends Readonly(FileSystem) {
 	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);
+			throw new ErrnoError(Errno.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');
+			throw ErrnoError.With('ENOENT', path, 'openFile');
 		}
 
 		if (!inode.toStats().hasAccess(flagToMode(flag), cred)) {
-			throw ApiError.With('EACCES', path, 'openFile');
+			throw ErrnoError.With('EACCES', path, 'openFile');
 		}
 
 		if (inode.isDirectory()) {
@@ -446,28 +450,28 @@ export abstract class IndexFS<TData> extends Readonly(FileSystem) {
 		// Check if it exists.
 		const inode = this._index.get(path);
 		if (!inode) {
-			throw ApiError.With('ENOENT', path, 'readdir');
+			throw ErrnoError.With('ENOENT', path, 'readdir');
 		}
 
 		if (inode.isDirectory()) {
 			return inode.listing;
 		}
 
-		throw ApiError.With('ENOTDIR', path, 'readdir');
+		throw ErrnoError.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');
+			throw ErrnoError.With('ENOENT', path, 'readdir');
 		}
 
 		if (inode.isDirectory()) {
 			return inode.listing;
 		}
 
-		throw ApiError.With('ENOTDIR', path, 'readdir');
+		throw ErrnoError.With('ENOTDIR', path, 'readdir');
 	}
 
 	protected abstract statFileInode(inode: IndexFileInode<TData>, path: string): Promise<Stats>;
@@ -491,10 +495,10 @@ export abstract class SyncIndexFS<TData> extends IndexFS<TData> {
 
 export abstract class AsyncIndexFS<TData> extends IndexFS<TData> {
 	protected statFileInodeSync(inode: IndexFileInode<TData>, path: string): Stats {
-		throw ApiError.With('ENOSYS', path, 'AsyncIndexFS.statFileInodeSync');
+		throw ErrnoError.With('ENOSYS', path, 'AsyncIndexFS.statFileInodeSync');
 	}
 
 	protected openFileInodeSync(inode: IndexFileInode<TData>, path: string, flag: string): NoSyncFile<this> {
-		throw ApiError.With('ENOSYS', path, 'AsyncIndexFS.openFileInodeSync');
+		throw ErrnoError.With('ENOSYS', path, 'AsyncIndexFS.openFileInodeSync');
 	}
 }

package/src/backends/Locked.ts

@@ -1,3 +1,4 @@
+import { ErrnoError } from '../error.js';
 import type { Cred } from '../cred.js';
 import type { File } from '../file.js';
 import type { FileSystem, FileSystemMetadata } from '../filesystem.js';
@@ -39,23 +40,23 @@ export class LockedFS<FS extends FileSystem> implements FileSystem {
 
 	public renameSync(oldPath: string, newPath: string, cred: Cred): void {
 		if (this._mu.isLocked(oldPath)) {
-			throw new Error('invalid sync call');
+			throw ErrnoError.With('EBUSY', oldPath, 'rename');
 		}
 		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);
+	public async stat(path: string, cred: Cred): Promise<Stats> {
+		await this._mu.lock(path);
+		const stats = await this.fs.stat(path, cred);
+		this._mu.unlock(path);
 		return stats;
 	}
 
-	public statSync(p: string, cred: Cred): Stats {
-		if (this._mu.isLocked(p)) {
-			throw new Error('invalid sync call');
+	public statSync(path: string, cred: Cred): Stats {
+		if (this._mu.isLocked(path)) {
+			throw ErrnoError.With('EBUSY', path, 'stat');
 		}
-		return this.fs.statSync(p, cred);
+		return this.fs.statSync(path, cred);
 	}
 
 	public async openFile(path: string, flag: string, cred: Cred): Promise<File> {
@@ -67,7 +68,7 @@ export class LockedFS<FS extends FileSystem> implements FileSystem {
 
 	public openFileSync(path: string, flag: string, cred: Cred): File {
 		if (this._mu.isLocked(path)) {
-			throw new Error('invalid sync call');
+			throw ErrnoError.With('EBUSY', path, 'openFile');
 		}
 		return this.fs.openFileSync(path, flag, cred);
 	}
@@ -81,7 +82,7 @@ export class LockedFS<FS extends FileSystem> implements FileSystem {
 
 	public createFileSync(path: string, flag: string, mode: number, cred: Cred): File {
 		if (this._mu.isLocked(path)) {
-			throw new Error('invalid sync call');
+			throw ErrnoError.With('EBUSY', path, 'createFile');
 		}
 		return this.fs.createFileSync(path, flag, mode, cred);
 	}
@@ -92,65 +93,65 @@ export class LockedFS<FS extends FileSystem> implements FileSystem {
 		this._mu.unlock(p);
 	}
 
-	public unlinkSync(p: string, cred: Cred): void {
-		if (this._mu.isLocked(p)) {
-			throw new Error('invalid sync call');
+	public unlinkSync(path: string, cred: Cred): void {
+		if (this._mu.isLocked(path)) {
+			throw ErrnoError.With('EBUSY', path, 'unlink');
 		}
-		return this.fs.unlinkSync(p, cred);
+		return this.fs.unlinkSync(path, 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 async rmdir(path: string, cred: Cred): Promise<void> {
+		await this._mu.lock(path);
+		await this.fs.rmdir(path, cred);
+		this._mu.unlock(path);
 	}
 
-	public rmdirSync(p: string, cred: Cred): void {
-		if (this._mu.isLocked(p)) {
-			throw new Error('invalid sync call');
+	public rmdirSync(path: string, cred: Cred): void {
+		if (this._mu.isLocked(path)) {
+			throw ErrnoError.With('EBUSY', path, 'rmdir');
 		}
-		return this.fs.rmdirSync(p, cred);
+		return this.fs.rmdirSync(path, 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 async mkdir(path: string, mode: number, cred: Cred): Promise<void> {
+		await this._mu.lock(path);
+		await this.fs.mkdir(path, mode, cred);
+		this._mu.unlock(path);
 	}
 
-	public mkdirSync(p: string, mode: number, cred: Cred): void {
-		if (this._mu.isLocked(p)) {
-			throw new Error('invalid sync call');
+	public mkdirSync(path: string, mode: number, cred: Cred): void {
+		if (this._mu.isLocked(path)) {
+			throw ErrnoError.With('EBUSY', path, 'mkdir');
 		}
-		return this.fs.mkdirSync(p, mode, cred);
+		return this.fs.mkdirSync(path, 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);
+	public async readdir(path: string, cred: Cred): Promise<string[]> {
+		await this._mu.lock(path);
+		const files = await this.fs.readdir(path, cred);
+		this._mu.unlock(path);
 		return files;
 	}
 
-	public readdirSync(p: string, cred: Cred): string[] {
-		if (this._mu.isLocked(p)) {
-			throw new Error('invalid sync call');
+	public readdirSync(path: string, cred: Cred): string[] {
+		if (this._mu.isLocked(path)) {
+			throw ErrnoError.With('EBUSY', path, 'readdir');
 		}
-		return this.fs.readdirSync(p, cred);
+		return this.fs.readdirSync(path, 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);
+	public async exists(path: string, cred: Cred): Promise<boolean> {
+		await this._mu.lock(path);
+		const exists = await this.fs.exists(path, cred);
+		this._mu.unlock(path);
 		return exists;
 	}
 
-	public existsSync(p: string, cred: Cred): boolean {
-		if (this._mu.isLocked(p)) {
-			throw new Error('invalid sync call');
+	public existsSync(path: string, cred: Cred): boolean {
+		if (this._mu.isLocked(path)) {
+			throw ErrnoError.With('EBUSY', path, 'exists');
 		}
-		return this.fs.existsSync(p, cred);
+		return this.fs.existsSync(path, cred);
 	}
 
 	public async link(srcpath: string, dstpath: string, cred: Cred): Promise<void> {
@@ -161,7 +162,7 @@ export class LockedFS<FS extends FileSystem> implements FileSystem {
 
 	public linkSync(srcpath: string, dstpath: string, cred: Cred): void {
 		if (this._mu.isLocked(srcpath)) {
-			throw new Error('invalid sync call');
+			throw ErrnoError.With('EBUSY', srcpath, 'link');
 		}
 		return this.fs.linkSync(srcpath, dstpath, cred);
 	}
@@ -174,7 +175,7 @@ export class LockedFS<FS extends FileSystem> implements FileSystem {
 
 	public syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void {
 		if (this._mu.isLocked(path)) {
-			throw new Error('invalid sync call');
+			throw ErrnoError.With('EBUSY', path, 'sync');
 		}
 		return this.fs.syncSync(path, data, stats);
 	}