@zenfs/core 2.5.7 → 2.6.0

package/dist/vfs/shared.d.ts

@@ -23,6 +23,7 @@ export declare function mount(this: V_Context, mountPoint: string, fs: FileSyste
 /**
  * Unmounts the file system at `mountPoint`.
  * @category Backends and Configuration
+ * @todo [BREAKING] make this `async` and `await` vcache sync
  */
 export declare function umount(this: V_Context, mountPoint: string): void;
 /**

package/dist/vfs/shared.js

@@ -9,6 +9,7 @@ import { credentialsAllowRoot } from '../internal/credentials.js';
 import { withExceptionContext } from '../internal/error.js';
 import { join, resolve } from '../path.js';
 import { normalizePath } from '../utils.js';
+import { caches, VCache } from './vcache.js';
 /**
  * The map of mount points
  * @category Backends and Configuration
@@ -30,23 +31,38 @@ export function mount(mountPoint, fs) {
         throw err(withErrno('EINVAL', 'Mount point is already in use: ' + mountPoint));
     fs._mountPoint = mountPoint;
     mounts.set(mountPoint, fs);
+    if (!caches.has(fs.uuid))
+        caches.set(fs.uuid, new VCache(fs));
     info(`Mounted ${fs.name} on ${mountPoint}`);
     debug(`${fs.name} attributes: ${[...fs.attributes].map(([k, v]) => (v !== undefined && v !== null ? k + '=' + v : k)).join(', ')}`);
 }
 /**
  * Unmounts the file system at `mountPoint`.
  * @category Backends and Configuration
+ * @todo [BREAKING] make this `async` and `await` vcache sync
  */
 export function umount(mountPoint) {
     if (mountPoint[0] != '/')
         mountPoint = '/' + mountPoint;
     mountPoint = resolve.call(this, mountPoint);
-    if (!mounts.has(mountPoint)) {
+    const fs = mounts.get(mountPoint);
+    if (!fs) {
         warn(mountPoint + ' is already unmounted');
         return;
     }
-    mounts.delete(mountPoint);
-    notice('Unmounted ' + mountPoint);
+    const _done = () => {
+        caches.delete(fs.uuid);
+        mounts.delete(mountPoint);
+        notice('Unmounted ' + mountPoint);
+    };
+    try {
+        caches.get(fs.uuid)?.syncSync();
+        _done();
+    }
+    catch {
+        warn(`Could not flush to ${mountPoint} synchronously. Unmount is being deferred.`);
+        void caches.get(fs.uuid)?.sync().then(_done);
+    }
 }
 /**
  * Gets the internal `FileSystem` for the path, then returns it along with the path relative to the FS' root

package/dist/vfs/sync.js

@@ -1,10 +1,64 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
 import { setUVMessage, UV } from 'kerium';
 import { decodeUTF8 } from 'utilium';
 import * as constants from '../constants.js';
 import { contextOf } from '../internal/contexts.js';
+import { wrap } from '../internal/error.js';
 import { hasAccess, isDirectory, isSymbolicLink } from '../internal/inode.js';
 import { basename, dirname, join, parse, resolve as resolvePath } from '../path.js';
 import { normalizeMode, normalizePath } from '../utils.js';
+import { cacheOf, lockPathSync } from './vcache.js';
 import { checkAccess } from './config.js';
 import { Dirent, ifToDt } from './dir.js';
 import { Handle } from './file.js';
@@ -23,8 +77,8 @@ export function resolve($, path, preserveSymlinks, extra) {
     that means we don't need to perform any resolution for parent directories. */
     try {
         const resolved = resolveMount(path, $);
-        // Stat it to make sure it exists
-        const stats = resolved.fs.statSync(resolved.path);
+        // Stat it to make sure it exists. The vnode cache takes precedence since it may have unsynced changes
+        const stats = cacheOf(resolved.fs).get(resolved.path)?.inode ?? resolved.fs.statSync(resolved.path);
         if (!isSymbolicLink(stats) || preserveSymlinks) {
             return { ...resolved, fullPath: path, stats };
         }
@@ -42,7 +96,7 @@ export function resolve($, path, preserveSymlinks, extra) {
     const resolved = resolveMount(maybePath, $);
     let stats;
     try {
-        stats = resolved.fs.statSync(resolved.path);
+        stats = cacheOf(resolved.fs).get(resolved.path)?.inode ?? resolved.fs.statSync(resolved.path);
     }
     catch (e) {
         if (e.code === 'ENOENT')
@@ -72,45 +126,57 @@ export function open(path, opt) {
         // nothing
     }
     if (!stats) {
-        if (!(flag & constants.O_CREAT)) {
-            throw UV('ENOENT', 'open', path);
-        }
-        // Create the file
-        const parentStats = fs.statSync(dirname(resolved));
-        if (checkAccess && !hasAccess(this, parentStats, constants.W_OK)) {
-            throw UV('EACCES', 'open', path);
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            if (!(flag & constants.O_CREAT)) {
+                throw UV('ENOENT', 'open', path);
+            }
+            // Create the file
+            const parentPath = dirname(resolved);
+            const parentStats = fs.statSync(parentPath);
+            if (checkAccess && !hasAccess(this, parentStats, constants.W_OK)) {
+                throw UV('EACCES', 'open', path);
+            }
+            if (!isDirectory(parentStats)) {
+                throw UV('ENOTDIR', 'open', path);
+            }
+            if (!opt.allowDirectory && mode & constants.S_IFDIR)
+                throw UV('EISDIR', 'open', path);
+            // Serialize entry creation with other operations on the parent directory
+            const _ = __addDisposableResource(env_1, lockPathSync(fs, parentPath, 'rw', parentStats), false);
+            const { euid: uid, egid: gid } = contextOf(this).credentials;
+            const inode = fs.createFileSync(resolved, {
+                mode,
+                uid: parentStats.mode & constants.S_ISUID ? parentStats.uid : uid,
+                gid: parentStats.mode & constants.S_ISGID ? parentStats.gid : gid,
+            });
+            // A new entry in the parent directory, which is a 'rename' event
+            emitChange(this, 'rename', path);
+            return new Handle(this, path, resolved, flag, cacheOf(fs).ref(resolved, inode));
         }
-        if (!isDirectory(parentStats)) {
-            throw UV('ENOTDIR', 'open', path);
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
         }
-        if (!opt.allowDirectory && mode & constants.S_IFDIR)
-            throw UV('EISDIR', 'open', path);
-        if (checkAccess && !hasAccess(this, parentStats, constants.W_OK)) {
-            throw UV('EACCES', 'open', path);
+        finally {
+            __disposeResources(env_1);
         }
-        const { euid: uid, egid: gid } = contextOf(this).credentials;
-        const inode = fs.createFileSync(resolved, {
-            mode,
-            uid: parentStats.mode & constants.S_ISUID ? parentStats.uid : uid,
-            gid: parentStats.mode & constants.S_ISGID ? parentStats.gid : gid,
-        });
-        return new Handle(this, path, fs, resolved, flag, inode);
     }
     if (checkAccess && (!hasAccess(this, stats, mode) || !hasAccess(this, stats, flags.toMode(flag)))) {
         throw UV('EACCES', 'open', path);
     }
     if (flag & constants.O_EXCL)
         throw UV('EEXIST', 'open', path);
-    const file = new Handle(this, path, fs, resolved, flag, stats);
     if (!opt.allowDirectory && stats.mode & constants.S_IFDIR)
         throw UV('EISDIR', 'open', path);
+    const file = new Handle(this, path, resolved, flag, cacheOf(fs).ref(resolved, stats));
     if (flag & constants.O_TRUNC)
         file.truncateSync(0);
     return file;
 }
 export function readlink(path) {
     path = normalizePath(path);
-    const { fs, stats, path: resolved } = resolve(this, path, true);
+    const { fs, stats, path: resolved } = resolve(this, path, true, { syscall: 'readlink' });
     if (!stats)
         throw UV('ENOENT', 'readlink', path);
     if (checkAccess && !hasAccess(this, stats, constants.R_OK))
@@ -128,15 +194,26 @@ export function mkdir(path, options = {}) {
     const { euid: uid, egid: gid } = contextOf(this).credentials;
     const { mode = 0o777, recursive } = options;
     const __create = (path, resolved, parent) => {
-        if (checkAccess && !hasAccess(this, parent, constants.W_OK))
-            throw UV('EACCES', 'mkdir', dirname(path));
-        const inode = fs.mkdirSync(resolved, {
-            mode,
-            uid: parent.mode & constants.S_ISUID ? parent.uid : uid,
-            gid: parent.mode & constants.S_ISGID ? parent.gid : gid,
-        });
-        emitChange(this, 'rename', path);
-        return inode;
+        const env_2 = { stack: [], error: void 0, hasError: false };
+        try {
+            if (checkAccess && !hasAccess(this, parent, constants.W_OK))
+                throw UV('EACCES', 'mkdir', dirname(path));
+            const _ = __addDisposableResource(env_2, lockPathSync(fs, dirname(resolved), 'rw', parent), false);
+            const inode = wrap(fs, 'mkdirSync', { path, syscall: 'mkdir' })(resolved, {
+                mode,
+                uid: parent.mode & constants.S_ISUID ? parent.uid : uid,
+                gid: parent.mode & constants.S_ISGID ? parent.gid : gid,
+            });
+            emitChange(this, 'rename', path);
+            return inode;
+        }
+        catch (e_2) {
+            env_2.error = e_2;
+            env_2.hasError = true;
+        }
+        finally {
+            __disposeResources(env_2);
+        }
     };
     if (!recursive) {
         __create(path, resolved, fs.statSync(dirname(resolved)));
@@ -157,12 +234,27 @@ export function mkdir(path, options = {}) {
 export function readdir(path, options = {}) {
     path = normalizePath(path);
     const { fs, path: resolved } = resolve(this, path);
-    const stats = fs.statSync(resolved);
+    // Node reports `readdir` failures as `scandir`
+    const stats = cacheOf(fs).get(resolved)?.inode ?? wrap(fs, 'statSync', { path, syscall: 'scandir' })(resolved);
     if (checkAccess && !hasAccess(this, stats, constants.R_OK))
-        throw UV('EACCES', 'readdir', path);
+        throw UV('EACCES', 'scandir', path);
     if (!isDirectory(stats))
-        throw UV('ENOTDIR', 'readdir', path);
-    const entries = fs.readdirSync(resolved);
+        throw UV('ENOTDIR', 'scandir', path);
+    let entries;
+    {
+        const env_3 = { stack: [], error: void 0, hasError: false };
+        try {
+            const _ = __addDisposableResource(env_3, lockPathSync(fs, resolved, 'ro', stats), false);
+            entries = fs.readdirSync(resolved);
+        }
+        catch (e_3) {
+            env_3.error = e_3;
+            env_3.hasError = true;
+        }
+        finally {
+            __disposeResources(env_3);
+        }
+    }
     // Iterate over entries and handle recursive case if needed
     const values = [];
     const addEntry = (entry) => {
@@ -192,58 +284,94 @@ export function readdir(path, options = {}) {
     return values;
 }
 export function rename(oldPath, newPath) {
-    oldPath = normalizePath(oldPath);
-    newPath = normalizePath(newPath);
-    const $ex = { syscall: 'rename', path: oldPath, dest: newPath };
-    const src = resolve(this, oldPath, true, $ex);
-    const dst = resolveMount(newPath, this, $ex);
-    if (src.fs.uuid !== dst.fs.uuid)
-        throw UV('EXDEV', $ex);
-    if (dst.path.startsWith(src.path + '/'))
-        throw UV('EBUSY', $ex);
-    if (!src.stats)
-        throw UV('ENOENT', $ex);
-    const fs = src.fs;
-    const oldParent = fs.statSync(dirname(src.path));
-    const newParent = fs.statSync(dirname(dst.path));
-    let newStats;
+    const env_4 = { stack: [], error: void 0, hasError: false };
     try {
-        newStats = fs.statSync(dst.path);
+        oldPath = normalizePath(oldPath);
+        newPath = normalizePath(newPath);
+        const $ex = { syscall: 'rename', path: oldPath, dest: newPath };
+        const src = resolve(this, oldPath, true, $ex);
+        const dst = resolveMount(newPath, this, $ex);
+        if (src.fs.uuid !== dst.fs.uuid)
+            throw UV('EXDEV', $ex);
+        // A directory can not be moved inside itself
+        if (dst.path.startsWith(src.path + '/'))
+            throw UV('EINVAL', $ex);
+        if (!src.stats)
+            throw UV('ENOENT', $ex);
+        const fs = src.fs;
+        const oldParent = fs.statSync(dirname(src.path));
+        const newParent = fs.statSync(dirname(dst.path));
+        let newStats;
+        try {
+            newStats = fs.statSync(dst.path);
+        }
+        catch (e) {
+            if (e.code != 'ENOENT')
+                throw e;
+        }
+        if (checkAccess && (!hasAccess(this, oldParent, constants.R_OK) || !hasAccess(this, newParent, constants.W_OK)))
+            throw UV('EACCES', $ex);
+        if (newStats && !isDirectory(src.stats) && isDirectory(newStats))
+            throw UV('EISDIR', $ex);
+        if (newStats && isDirectory(src.stats) && !isDirectory(newStats))
+            throw UV('ENOTDIR', $ex);
+        const srcDir = dirname(src.path);
+        const dstDir = dirname(dst.path);
+        // Lock both parent directories, ordered by inode number to avoid ABBA deadlocks (like Linux's `lock_two_nondirectories`)
+        const parents = [
+            [srcDir, oldParent],
+            [dstDir, newParent],
+        ];
+        if (oldParent.ino > newParent.ino)
+            parents.reverse();
+        const _first = __addDisposableResource(env_4, lockPathSync(fs, parents[0][0], 'rw', parents[0][1]), false);
+        const _second = __addDisposableResource(env_4, oldParent.ino == newParent.ino ? null : lockPathSync(fs, parents[1][0], 'rw', parents[1][1]), false);
+        src.fs.renameSync(src.path, dst.path);
+        cacheOf(fs).rename(src.path, dst.path);
+        // Both names change which entries exist, so both are 'rename' events
+        emitChange(this, 'rename', oldPath);
+        emitChange(this, 'rename', newPath);
     }
-    catch (e) {
-        if (e.code != 'ENOENT')
-            throw e;
+    catch (e_4) {
+        env_4.error = e_4;
+        env_4.hasError = true;
+    }
+    finally {
+        __disposeResources(env_4);
     }
-    if (checkAccess && (!hasAccess(this, oldParent, constants.R_OK) || !hasAccess(this, newParent, constants.W_OK)))
-        throw UV('EACCES', $ex);
-    if (newStats && !isDirectory(src.stats) && isDirectory(newStats))
-        throw UV('EISDIR', $ex);
-    if (newStats && isDirectory(src.stats) && !isDirectory(newStats))
-        throw UV('ENOTDIR', $ex);
-    src.fs.renameSync(src.path, dst.path);
-    emitChange(this, 'rename', oldPath);
-    emitChange(this, 'change', newPath);
 }
 export function link(target, link) {
-    target = normalizePath(target);
-    link = normalizePath(link);
-    const $ex = { syscall: 'link', path: link, dest: target };
-    const { fs, path: resolved } = resolveMount(target, this, $ex);
-    const dst = resolveMount(link, this, $ex);
-    if (fs.uuid !== dst.fs.uuid)
-        throw UV('EXDEV', $ex);
-    const stats = fs.statSync(resolved);
-    if (checkAccess) {
-        if (!hasAccess(this, stats, constants.R_OK))
-            throw UV('EACCES', $ex);
-        const dirStats = fs.statSync(dirname(resolved));
-        if (!hasAccess(this, dirStats, constants.R_OK))
-            throw UV('EACCES', $ex);
-        const destStats = fs.statSync(dirname(dst.path));
-        if (!hasAccess(this, destStats, constants.W_OK))
-            throw UV('EACCES', $ex);
+    const env_5 = { stack: [], error: void 0, hasError: false };
+    try {
+        target = normalizePath(target);
+        link = normalizePath(link);
+        const $ex = { syscall: 'link', path: target, dest: link };
+        const { fs, path: resolved } = resolveMount(target, this, $ex);
+        const dst = resolveMount(link, this, $ex);
+        if (fs.uuid !== dst.fs.uuid)
+            throw UV('EXDEV', $ex);
+        const stats = fs.statSync(resolved);
+        if (checkAccess) {
+            if (!hasAccess(this, stats, constants.R_OK))
+                throw UV('EACCES', $ex);
+            const dirStats = fs.statSync(dirname(resolved));
+            if (!hasAccess(this, dirStats, constants.R_OK))
+                throw UV('EACCES', $ex);
+            const destStats = fs.statSync(dirname(dst.path));
+            if (!hasAccess(this, destStats, constants.W_OK))
+                throw UV('EACCES', $ex);
+        }
+        const _ = __addDisposableResource(env_5, lockPathSync(fs, dirname(dst.path), 'rw'), false);
+        fs.linkSync(resolved, dst.path);
+        cacheOf(fs).link(resolved, dst.path);
+    }
+    catch (e_5) {
+        env_5.error = e_5;
+        env_5.hasError = true;
+    }
+    finally {
+        __disposeResources(env_5);
     }
-    return fs.linkSync(resolved, dst.path);
 }
 export function stat(path, lstat) {
     path = normalizePath.call(this, path);
@@ -255,7 +383,8 @@ export function stat(path, lstat) {
         const { base, dir } = parse(path);
         const { fs, path: parent } = resolve(this, dir, false, extra);
         try {
-            stats = fs.statSync(base ? join(parent, base) : parent);
+            const target = base ? join(parent, base) : parent;
+            stats = cacheOf(fs).get(target)?.inode ?? fs.statSync(target);
         }
         catch (e) {
             setUVMessage(Object.assign(e, extra));

package/dist/vfs/vcache.d.ts

@@ -0,0 +1,66 @@
+import type { LockMode, LockRelease } from 'kerium/locks';
+import type { FileSystem } from '../internal/filesystem.js';
+import type { InodeLike } from '../internal/inode.js';
+import { VNode } from './vnode.js';
+/**
+ * The VFS-level cache of vnodes for a single file system. Modeled after Linux's dcache/icache.
+ *
+ * Vnodes are keyed by inode number, so hard links share a vnode.
+ * A vnode stays cached while it is referenced or dirty, and is evicted otherwise.
+ * @category VFS
+ * @todo Add LRU or something to limit memory usage
+ */
+export declare class VCache {
+    readonly fs: FileSystem;
+    protected byIno: Map<number, VNode>;
+    protected byPath: Map<string, VNode>;
+    constructor(fs: FileSystem);
+    /** Get the vnode for a path, if one is cached. Note paths are relative to the FS root, not the VFS root */
+    get(path: string): VNode | undefined;
+    /**
+     * Get or create the vnode for `path`, incrementing its reference count.
+     * Callers must `unref` the vnode when done with it.
+     */
+    ref(path: string, inode: InodeLike): VNode;
+    /** Release a reference to a vnode, evicting it if it is unreferenced and clean */
+    unref(node: VNode): void;
+    protected evict(node: VNode): void;
+    /** Update cached paths for a rename. Handles directories, whose descendants' paths change too */
+    rename(oldPath: string, newPath: string): void;
+    /** Add a path for a newly created hard link, if the target is cached */
+    link(targetPath: string, linkPath: string): void;
+    /** Remove a path for an unlink/rmdir. The vnode is kept if other paths (hard links) refer to it */
+    remove(path: string): void;
+    /** Sync all dirty vnodes to the backend */
+    sync(): Promise<void>;
+    /** Sync all dirty vnodes to the backend synchronously */
+    syncSync(): void;
+}
+/**
+ * All vnode caches, keyed by file system UUID.
+ * Keyed by UUID rather than the `FileSystem` object because `resolveMount`
+ * wraps file systems in a new exception-context proxy on every call.
+ * @category VFS
+ * @internal
+ */
+export declare const caches: Map<`${string}-${string}-${string}-${string}-${string}`, VCache>;
+/**
+ * Get the vnode cache for a file system, creating it if needed.
+ * @category VFS
+ * @internal
+ */
+export declare function cacheOf(fs: FileSystem): VCache;
+/**
+ * Ref and lock the vnode for a path, usually a parent directory during a namespace operation.
+ * The returned release function unlocks and unrefs the vnode.
+ * If `inode` is not provided and the vnode is not cached, the backend is `stat`ed.
+ * @category VFS
+ * @internal
+ */
+export declare function lockPath(fs: FileSystem, path: string, mode: LockMode, inode?: InodeLike): Promise<LockRelease>;
+/**
+ * Synchronous version of `lockPath`.
+ * @category VFS
+ * @internal
+ */
+export declare function lockPathSync(fs: FileSystem, path: string, mode: LockMode, inode?: InodeLike): LockRelease;