@zenfs/core 0.9.7 → 0.11.0

package/dist/backends/port/fs.js

@@ -0,0 +1,239 @@
+import { Errno, ErrnoError } from '../../error.js';
+import { File } from '../../file.js';
+import { Async, FileSystem } from '../../filesystem.js';
+import { Stats } from '../../stats.js';
+import { InMemory } from '../memory.js';
+import * as RPC from './rpc.js';
+export class PortFile extends File {
+    constructor(fs, fd, path, position) {
+        super();
+        this.fs = fs;
+        this.fd = fd;
+        this.path = path;
+        this.position = position;
+    }
+    rpc(method, ...args) {
+        return RPC.request({
+            scope: 'file',
+            fd: this.fd,
+            method,
+            args,
+        }, this.fs.options);
+    }
+    stat() {
+        return this.rpc('stat');
+    }
+    statSync() {
+        throw ErrnoError.With('ENOSYS', this.path, 'PortFile.stat');
+    }
+    truncate(len) {
+        return this.rpc('truncate', len);
+    }
+    truncateSync() {
+        throw ErrnoError.With('ENOSYS', this.path, 'PortFile.truncate');
+    }
+    write(buffer, offset, length, position) {
+        return this.rpc('write', buffer, offset, length, position);
+    }
+    writeSync() {
+        throw ErrnoError.With('ENOSYS', this.path, 'PortFile.write');
+    }
+    async read(buffer, offset, length, position) {
+        return (await this.rpc('read', buffer, offset, length, position));
+    }
+    readSync() {
+        throw ErrnoError.With('ENOSYS', this.path, 'PortFile.read');
+    }
+    chown(uid, gid) {
+        return this.rpc('chown', uid, gid);
+    }
+    chownSync() {
+        throw ErrnoError.With('ENOSYS', this.path, 'PortFile.chown');
+    }
+    chmod(mode) {
+        return this.rpc('chmod', mode);
+    }
+    chmodSync() {
+        throw ErrnoError.With('ENOSYS', this.path, 'PortFile.chmod');
+    }
+    utimes(atime, mtime) {
+        return this.rpc('utimes', atime, mtime);
+    }
+    utimesSync() {
+        throw ErrnoError.With('ENOSYS', this.path, 'PortFile.utimes');
+    }
+    _setType(type) {
+        return this.rpc('_setType', type);
+    }
+    _setTypeSync() {
+        throw ErrnoError.With('ENOSYS', this.path, 'PortFile._setType');
+    }
+    close() {
+        return this.rpc('close');
+    }
+    closeSync() {
+        throw ErrnoError.With('ENOSYS', this.path, 'PortFile.close');
+    }
+    sync() {
+        return this.rpc('sync');
+    }
+    syncSync() {
+        throw ErrnoError.With('ENOSYS', this.path, 'PortFile.sync');
+    }
+}
+/**
+ * PortFS lets you access a ZenFS instance that is running in a port, or the other way around.
+ *
+ * Note that synchronous operations are not permitted on the PortFS, regardless
+ * of the configuration option of the remote FS.
+ */
+export class PortFS extends Async(FileSystem) {
+    /**
+     * Constructs a new PortFS instance that connects with ZenFS running on
+     * the specified port.
+     */
+    constructor(options) {
+        super();
+        this.options = options;
+        /**
+         * @hidden
+         */
+        this._sync = InMemory.create({ name: 'port-tmpfs' });
+        this.port = options.port;
+        RPC.attach(this.port, RPC.handleResponse);
+    }
+    metadata() {
+        return {
+            ...super.metadata(),
+            name: 'PortFS',
+        };
+    }
+    rpc(method, ...args) {
+        return RPC.request({
+            scope: 'fs',
+            method,
+            args,
+        }, { ...this.options, fs: this });
+    }
+    async ready() {
+        await this.rpc('ready');
+        await super.ready();
+    }
+    rename(oldPath, newPath, cred) {
+        return this.rpc('rename', oldPath, newPath, cred);
+    }
+    async stat(path, cred) {
+        return new Stats(await this.rpc('stat', path, cred));
+    }
+    sync(path, data, stats) {
+        return this.rpc('sync', path, data, stats);
+    }
+    openFile(path, flag, cred) {
+        return this.rpc('openFile', path, flag, cred);
+    }
+    createFile(path, flag, mode, cred) {
+        return this.rpc('createFile', path, flag, mode, cred);
+    }
+    unlink(path, cred) {
+        return this.rpc('unlink', path, cred);
+    }
+    rmdir(path, cred) {
+        return this.rpc('rmdir', path, cred);
+    }
+    mkdir(path, mode, cred) {
+        return this.rpc('mkdir', path, mode, cred);
+    }
+    readdir(path, cred) {
+        return this.rpc('readdir', path, cred);
+    }
+    exists(path, cred) {
+        return this.rpc('exists', path, cred);
+    }
+    link(srcpath, dstpath, cred) {
+        return this.rpc('link', srcpath, dstpath, cred);
+    }
+}
+let nextFd = 0;
+const descriptors = new Map();
+async function handleRequest(port, fs, request) {
+    if (!RPC.isMessage(request)) {
+        return;
+    }
+    const { method, args, id, scope, stack } = request;
+    let value, error = false;
+    try {
+        switch (scope) {
+            case 'fs':
+                // @ts-expect-error 2556
+                value = await fs[method](...args);
+                if (value instanceof File) {
+                    descriptors.set(++nextFd, value);
+                    value = {
+                        fd: nextFd,
+                        path: value.path,
+                        position: value.position,
+                    };
+                }
+                break;
+            case 'file':
+                const { fd } = request;
+                if (!descriptors.has(fd)) {
+                    throw new ErrnoError(Errno.EBADF);
+                }
+                // @ts-expect-error 2556
+                value = await descriptors.get(fd)[method](...args);
+                if (method == 'close') {
+                    descriptors.delete(fd);
+                }
+                break;
+            default:
+                return;
+        }
+    }
+    catch (e) {
+        value = e;
+        error = true;
+    }
+    port.postMessage({
+        _zenfs: true,
+        scope,
+        id,
+        error,
+        method,
+        stack,
+        value: value instanceof ErrnoError ? value.toJSON() : value,
+    });
+}
+export function attachFS(port, fs) {
+    RPC.attach(port, request => handleRequest(port, fs, request));
+}
+export function detachFS(port, fs) {
+    RPC.detach(port, request => handleRequest(port, fs, request));
+}
+export const Port = {
+    name: 'Port',
+    options: {
+        port: {
+            type: 'object',
+            required: true,
+            description: 'The target port that you want to connect to',
+            validator(port) {
+                // Check for a `postMessage` function.
+                if (typeof port?.postMessage != 'function') {
+                    throw new ErrnoError(Errno.EINVAL, 'option must be a port.');
+                }
+            },
+        },
+        timeout: {
+            type: 'number',
+            required: false,
+            description: 'How long to wait before the request times out',
+        },
+    },
+    async isAvailable() {
+        return true;
+    },
+    create(options) {
+        return new PortFS(options);
+    },
+};

package/dist/backends/port/rpc.d.ts

@@ -0,0 +1,60 @@
+/// <reference types="node" resolution-mode="require"/>
+/// <reference types="node" resolution-mode="require"/>
+import type { TransferListItem } from 'worker_threads';
+import { type PortFS } from './fs.js';
+type _MessageEvent<T = any> = T | {
+    data: T;
+};
+export interface Port {
+    postMessage(value: unknown, transferList?: ReadonlyArray<TransferListItem>): void;
+    on?(event: 'message', listener: (value: unknown) => void): this;
+    off?(event: 'message', listener: (value: unknown) => void): this;
+    addEventListener?(type: 'message', listener: (this: Port, ev: _MessageEvent) => void): void;
+    removeEventListener?(type: 'message', listener: (this: Port, ev: _MessageEvent) => void): void;
+}
+export interface Options {
+    /**
+     * The target port that you want to connect to, or the current port if in a port context.
+     */
+    port: Port;
+    /**
+     * How long to wait for a request to complete
+     */
+    timeout?: number;
+}
+/**
+ * An RPC message
+ */
+export interface Message<TScope extends string = string, TMethod extends string = string> {
+    _zenfs: true;
+    scope: TScope;
+    id: string;
+    method: TMethod;
+    stack: string;
+}
+export interface Request<TScope extends string = string, TMethod extends string = string, TArgs extends unknown[] = unknown[]> extends Message<TScope, TMethod> {
+    args: TArgs;
+}
+export interface Response<TScope extends string = string, TMethod extends string = string, TValue = unknown> extends Message<TScope, TMethod> {
+    error: boolean;
+    value: Awaited<TValue> extends File ? FileData : Awaited<TValue>;
+}
+export interface FileData {
+    fd: number;
+    path: string;
+    position: number;
+}
+export { FileData as File };
+export declare function isMessage(arg: unknown): arg is Message<string, string>;
+type _Executor = Parameters<ConstructorParameters<typeof Promise<any>>[0]>;
+export interface Executor {
+    resolve: _Executor[0];
+    reject: _Executor[1];
+    fs?: PortFS;
+}
+export declare function request<const TRequest extends Request, TValue>(request: Omit<TRequest, 'id' | 'stack' | '_zenfs'>, { port, timeout, fs }?: Partial<Options> & {
+    fs?: PortFS;
+}): Promise<TValue>;
+export declare function handleResponse<const TResponse extends Response>(response: TResponse): void;
+export declare function attach<T extends Message>(port: Port, handler: (message: T) => unknown): void;
+export declare function detach<T extends Message>(port: Port, handler: (message: T) => unknown): void;

package/dist/backends/port/rpc.js

@@ -0,0 +1,71 @@
+import { ErrnoError, Errno } from '../../error.js';
+import { PortFile } from './fs.js';
+function isFileData(value) {
+    return typeof value == 'object' && value != null && 'fd' in value && 'path' in value && 'position' in value;
+}
+// general types
+export function isMessage(arg) {
+    return typeof arg == 'object' && arg != null && '_zenfs' in arg && !!arg._zenfs;
+}
+const executors = new Map();
+export function request(request, { port, timeout = 1000, fs } = {}) {
+    const stack = new Error().stack.slice('Error:'.length);
+    if (!port) {
+        throw ErrnoError.With('EINVAL');
+    }
+    return new Promise((resolve, reject) => {
+        const id = Math.random().toString(16).slice(10);
+        executors.set(id, { resolve, reject, fs });
+        port.postMessage({ ...request, _zenfs: true, id, stack });
+        setTimeout(() => {
+            const error = new ErrnoError(Errno.EIO, 'RPC Failed');
+            error.stack += stack;
+            reject(error);
+        }, timeout);
+    });
+}
+export function handleResponse(response) {
+    if (!isMessage(response)) {
+        return;
+    }
+    const { id, value, error, stack } = response;
+    if (!executors.has(id)) {
+        const error = new ErrnoError(Errno.EIO, 'Invalid RPC id:' + id);
+        error.stack += stack;
+        throw error;
+    }
+    const { resolve, reject, fs } = executors.get(id);
+    if (error) {
+        const e = ErrnoError.fromJSON(value);
+        e.stack += stack;
+        reject(e);
+        executors.delete(id);
+        return;
+    }
+    if (isFileData(value)) {
+        const { fd, path, position } = value;
+        const file = new PortFile(fs, fd, path, position);
+        resolve(file);
+        executors.delete(id);
+        return;
+    }
+    resolve(value);
+    executors.delete(id);
+    return;
+}
+export function attach(port, handler) {
+    if (!port) {
+        throw ErrnoError.With('EINVAL');
+    }
+    port['on' in port ? 'on' : 'addEventListener']('message', (message) => {
+        handler('data' in message ? message.data : message);
+    });
+}
+export function detach(port, handler) {
+    if (!port) {
+        throw ErrnoError.With('EINVAL');
+    }
+    port['off' in port ? 'off' : 'removeEventListener']('message', (message) => {
+        handler('data' in message ? message.data : message);
+    });
+}

package/dist/backends/store/fs.d.ts

@@ -0,0 +1,169 @@
+import type { Cred } from '../../cred.js';
+import { PreloadFile } from '../../file.js';
+import { FileSystem, type FileSystemMetadata } from '../../filesystem.js';
+import { type Ino, Inode } from '../../inode.js';
+import { type Stats, FileType } from '../../stats.js';
+import type { Store, Transaction } from './store.js';
+/**
+ * A synchronous key-value file system. Uses a SyncStore to store the data.
+ *
+ * We use a unique ID for each node in the file system. The root node has a fixed ID.
+ * @todo Introduce Node ID caching.
+ * @todo Check modes.
+ * @internal
+ */
+export declare class StoreFS extends FileSystem {
+    private $store;
+    protected get store(): Store;
+    protected _store?: Store;
+    private _initialized;
+    ready(): Promise<void>;
+    constructor($store: Store | Promise<Store>);
+    metadata(): FileSystemMetadata;
+    /**
+     * Delete all contents stored in the file system.
+     */
+    empty(): Promise<void>;
+    /**
+     * Delete all contents stored in the file system.
+     */
+    emptySync(): void;
+    /**
+     * @todo Make rename compatible with the cache.
+     */
+    rename(oldPath: string, newPath: string, cred: Cred): Promise<void>;
+    renameSync(oldPath: string, newPath: string, cred: Cred): void;
+    stat(path: string, cred: Cred): Promise<Stats>;
+    statSync(path: string, cred: Cred): Stats;
+    createFile(path: string, flag: string, mode: number, cred: Cred): Promise<PreloadFile<this>>;
+    createFileSync(path: string, flag: string, mode: number, cred: Cred): PreloadFile<this>;
+    openFile(path: string, flag: string, cred: Cred): Promise<PreloadFile<this>>;
+    openFileSync(path: string, flag: string, cred: Cred): PreloadFile<this>;
+    unlink(path: string, cred: Cred): Promise<void>;
+    unlinkSync(path: string, cred: Cred): void;
+    rmdir(path: string, cred: Cred): Promise<void>;
+    rmdirSync(path: string, cred: Cred): void;
+    mkdir(path: string, mode: number, cred: Cred): Promise<void>;
+    mkdirSync(path: string, mode: number, cred: Cred): void;
+    readdir(path: string, cred: Cred): Promise<string[]>;
+    readdirSync(path: string, cred: Cred): string[];
+    /**
+     * Updated the inode and data node at the given path
+     * @todo Ensure mtime updates properly, and use that to determine if a data update is required.
+     */
+    sync(path: string, data: Uint8Array, stats: Readonly<Stats>): Promise<void>;
+    /**
+     * Updated the inode and data node at the given path
+     * @todo Ensure mtime updates properly, and use that to determine if a data update is required.
+     */
+    syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void;
+    link(existing: string, newpath: string, cred: Cred): Promise<void>;
+    linkSync(existing: string, newpath: string, cred: Cred): void;
+    /**
+     * Checks if the root directory exists. Creates it if it doesn't.
+     */
+    private makeRootDirectory;
+    /**
+     * Checks if the root directory exists. Creates it if it doesn't.
+     */
+    protected makeRootDirectorySync(): void;
+    /**
+     * Helper function for findINode.
+     * @param parent The parent directory of the file we are attempting to find.
+     * @param filename The filename of the inode we are attempting to find, minus
+     *   the parent.
+     */
+    private _findINode;
+    /**
+     * Helper function for findINode.
+     * @param parent The parent directory of the file we are attempting to find.
+     * @param filename The filename of the inode we are attempting to find, minus
+     *   the parent.
+     * @return string The ID of the file's inode in the file system.
+     */
+    protected _findINodeSync(tx: Transaction, parent: string, filename: string, visited?: Set<string>): Ino;
+    /**
+     * Finds the Inode of the given path.
+     * @param path The path to look up.
+     * @todo memoize/cache
+     */
+    private findINode;
+    /**
+     * Finds the Inode of the given path.
+     * @param path The path to look up.
+     * @return The Inode of the path p.
+     * @todo memoize/cache
+     */
+    protected findINodeSync(tx: Transaction, path: string, visited?: Set<string>): Inode;
+    /**
+     * Given the ID of a node, retrieves the corresponding Inode.
+     * @param tx The transaction to use.
+     * @param path The corresponding path to the file (used for error messages).
+     * @param id The ID to look up.
+     */
+    private getINode;
+    /**
+     * Given the ID of a node, retrieves the corresponding Inode.
+     * @param tx The transaction to use.
+     * @param path The corresponding path to the file (used for error messages).
+     * @param id The ID to look up.
+     */
+    protected getINodeSync(tx: Transaction, id: Ino, path: string): Inode;
+    /**
+     * Given the Inode of a directory, retrieves the corresponding directory
+     * listing.
+     */
+    private getDirListing;
+    /**
+     * Given the Inode of a directory, retrieves the corresponding directory listing.
+     */
+    protected getDirListingSync(tx: Transaction, inode: Inode, p?: string): {
+        [fileName: string]: Ino;
+    };
+    /**
+     * Adds a new node under a random ID. Retries before giving up in
+     * the exceedingly unlikely chance that we try to reuse a random ino.
+     */
+    private addNew;
+    /**
+     * Creates a new node under a random ID. Retries before giving up in
+     * the exceedingly unlikely chance that we try to reuse a random ino.
+     * @return The ino that the data was stored under.
+     */
+    protected addNewSync(tx: Transaction, data: Uint8Array, path: string): Ino;
+    /**
+     * Commits a new file (well, a FILE or a DIRECTORY) to the file system with
+     * the given mode.
+     * Note: This will commit the transaction.
+     * @param path The path to the new file.
+     * @param type The type of the new file.
+     * @param mode The mode to create the new file with.
+     * @param cred The UID/GID to create the file with
+     * @param data The data to store at the file's data node.
+     */
+    private commitNew;
+    /**
+     * Commits a new file (well, a FILE or a DIRECTORY) to the file system with the given mode.
+     * Note: This will commit the transaction.
+     * @param path The path to the new file.
+     * @param type The type of the new file.
+     * @param mode The mode to create the new file with.
+     * @param data The data to store at the file's data node.
+     * @return The Inode for the new file.
+     */
+    protected commitNewSync(path: string, type: FileType, mode: number, cred: Cred, data?: Uint8Array): Inode;
+    /**
+     * Remove all traces of the given path from the file system.
+     * @param path The path to remove from the file system.
+     * @param isDir Does the path belong to a directory, or a file?
+     * @todo Update mtime.
+     */
+    private remove;
+    /**
+     * Remove all traces of the given path from the file system.
+     * @param path The path to remove from the file system.
+     * @param isDir Does the path belong to a directory, or a file?
+     * @todo Update mtime.
+     */
+    protected removeSync(path: string, isDir: boolean, cred: Cred): void;
+}