@zenfs/core 0.0.1

package/dist/backends/AsyncStore.js

@@ -0,0 +1,620 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import * as path from 'path';
+import { ApiError, ErrorCode } from '../ApiError';
+import { W_OK, R_OK } from '../emulation/constants';
+import { PreloadFile, FileFlag } from '../file';
+import { BaseFileSystem } from '../filesystem';
+import Inode from '../inode';
+import { FileType } from '../stats';
+import { ROOT_NODE_ID, randomUUID, getEmptyDirNode } from '../utils';
+class LRUNode {
+    constructor(key, value) {
+        this.key = key;
+        this.value = value;
+        this.prev = null;
+        this.next = null;
+    }
+}
+// Adapted from https://chrisrng.svbtle.com/lru-cache-in-javascript
+class LRUCache {
+    constructor(limit) {
+        this.limit = limit;
+        this.size = 0;
+        this.map = {};
+        this.head = null;
+        this.tail = null;
+    }
+    /**
+     * Change or add a new value in the cache
+     * We overwrite the entry if it already exists
+     */
+    set(key, value) {
+        const node = new LRUNode(key, value);
+        if (this.map[key]) {
+            this.map[key].value = node.value;
+            this.remove(node.key);
+        }
+        else {
+            if (this.size >= this.limit) {
+                delete this.map[this.tail.key];
+                this.size--;
+                this.tail = this.tail.prev;
+                this.tail.next = null;
+            }
+        }
+        this.setHead(node);
+    }
+    /* Retrieve a single entry from the cache */
+    get(key) {
+        if (this.map[key]) {
+            const value = this.map[key].value;
+            const node = new LRUNode(key, value);
+            this.remove(key);
+            this.setHead(node);
+            return value;
+        }
+        else {
+            return null;
+        }
+    }
+    /* Remove a single entry from the cache */
+    remove(key) {
+        const node = this.map[key];
+        if (!node) {
+            return;
+        }
+        if (node.prev !== null) {
+            node.prev.next = node.next;
+        }
+        else {
+            this.head = node.next;
+        }
+        if (node.next !== null) {
+            node.next.prev = node.prev;
+        }
+        else {
+            this.tail = node.prev;
+        }
+        delete this.map[key];
+        this.size--;
+    }
+    /* Resets the entire cache - Argument limit is optional to be reset */
+    removeAll() {
+        this.size = 0;
+        this.map = {};
+        this.head = null;
+        this.tail = null;
+    }
+    setHead(node) {
+        node.next = this.head;
+        node.prev = null;
+        if (this.head !== null) {
+            this.head.prev = node;
+        }
+        this.head = node;
+        if (this.tail === null) {
+            this.tail = node;
+        }
+        this.size++;
+        this.map[node.key] = node;
+    }
+}
+export class AsyncKeyValueFile extends PreloadFile {
+    constructor(_fs, _path, _flag, _stat, contents) {
+        super(_fs, _path, _flag, _stat, contents);
+    }
+    sync() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.isDirty()) {
+                return;
+            }
+            yield this._fs._sync(this.getPath(), this.getBuffer(), this.getStats());
+            this.resetDirty();
+        });
+    }
+    close() {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.sync();
+        });
+    }
+}
+/**
+ * An "Asynchronous key-value file system". Stores data to/retrieves data from
+ * an underlying asynchronous key-value store.
+ */
+export class AsyncKeyValueFileSystem extends BaseFileSystem {
+    static isAvailable() {
+        return true;
+    }
+    constructor(cacheSize) {
+        super();
+        this._cache = null;
+        if (cacheSize > 0) {
+            this._cache = new LRUCache(cacheSize);
+        }
+    }
+    /**
+     * Initializes the file system. Typically called by subclasses' async
+     * constructors.
+     */
+    init(store) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.store = store;
+            // INVARIANT: Ensure that the root exists.
+            yield this.makeRootDirectory();
+        });
+    }
+    getName() {
+        return this.store.name();
+    }
+    isReadOnly() {
+        return false;
+    }
+    supportsSymlinks() {
+        return false;
+    }
+    supportsProps() {
+        return true;
+    }
+    supportsSynch() {
+        return false;
+    }
+    /**
+     * Delete all contents stored in the file system.
+     */
+    empty() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this._cache) {
+                this._cache.removeAll();
+            }
+            yield this.store.clear();
+            // INVARIANT: Root always exists.
+            yield this.makeRootDirectory();
+        });
+    }
+    access(p, mode, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const tx = this.store.beginTransaction('readonly');
+            const inode = yield this.findINode(tx, p);
+            if (!inode) {
+                throw ApiError.ENOENT(p);
+            }
+            if (!inode.toStats().hasAccess(mode, cred)) {
+                throw ApiError.EACCES(p);
+            }
+        });
+    }
+    /**
+     * @todo Make rename compatible with the cache.
+     */
+    rename(oldPath, newPath, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const c = this._cache;
+            if (this._cache) {
+                // Clear and disable cache during renaming process.
+                this._cache = null;
+                c.removeAll();
+            }
+            try {
+                const tx = this.store.beginTransaction('readwrite'), oldParent = path.dirname(oldPath), oldName = path.basename(oldPath), newParent = path.dirname(newPath), newName = path.basename(newPath), 
+                // Remove oldPath from parent's directory listing.
+                oldDirNode = yield this.findINode(tx, oldParent), oldDirList = yield this.getDirListing(tx, oldParent, oldDirNode);
+                if (!oldDirNode.toStats().hasAccess(W_OK, cred)) {
+                    throw ApiError.EACCES(oldPath);
+                }
+                if (!oldDirList[oldName]) {
+                    throw ApiError.ENOENT(oldPath);
+                }
+                const nodeId = oldDirList[oldName];
+                delete oldDirList[oldName];
+                // Invariant: Can't move a folder inside itself.
+                // This funny little hack ensures that the check passes only if oldPath
+                // is a subpath of newParent. We append '/' to avoid matching folders that
+                // are a substring of the bottom-most folder in the path.
+                if ((newParent + '/').indexOf(oldPath + '/') === 0) {
+                    throw new ApiError(ErrorCode.EBUSY, oldParent);
+                }
+                // Add newPath to parent's directory listing.
+                let newDirNode, newDirList;
+                if (newParent === oldParent) {
+                    // Prevent us from re-grabbing the same directory listing, which still
+                    // contains oldName.
+                    newDirNode = oldDirNode;
+                    newDirList = oldDirList;
+                }
+                else {
+                    newDirNode = yield this.findINode(tx, newParent);
+                    newDirList = yield this.getDirListing(tx, newParent, newDirNode);
+                }
+                if (newDirList[newName]) {
+                    // If it's a file, delete it.
+                    const newNameNode = yield this.getINode(tx, newPath, newDirList[newName]);
+                    if (newNameNode.isFile()) {
+                        try {
+                            yield tx.del(newNameNode.id);
+                            yield tx.del(newDirList[newName]);
+                        }
+                        catch (e) {
+                            yield tx.abort();
+                            throw e;
+                        }
+                    }
+                    else {
+                        // If it's a directory, throw a permissions error.
+                        throw ApiError.EPERM(newPath);
+                    }
+                }
+                newDirList[newName] = nodeId;
+                // Commit the two changed directory listings.
+                try {
+                    yield tx.put(oldDirNode.id, Buffer.from(JSON.stringify(oldDirList)), true);
+                    yield tx.put(newDirNode.id, Buffer.from(JSON.stringify(newDirList)), true);
+                }
+                catch (e) {
+                    yield tx.abort();
+                    throw e;
+                }
+                yield tx.commit();
+            }
+            finally {
+                if (c) {
+                    this._cache = c;
+                }
+            }
+        });
+    }
+    stat(p, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const tx = this.store.beginTransaction('readonly');
+            const inode = yield this.findINode(tx, p);
+            const stats = inode.toStats();
+            if (!stats.hasAccess(R_OK, cred)) {
+                throw ApiError.EACCES(p);
+            }
+            return stats;
+        });
+    }
+    createFile(p, flag, mode, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const tx = this.store.beginTransaction('readwrite'), data = Buffer.alloc(0), newFile = yield this.commitNewFile(tx, p, FileType.FILE, mode, cred, data);
+            // Open the file.
+            return new AsyncKeyValueFile(this, p, flag, newFile.toStats(), data);
+        });
+    }
+    openFile(p, flag, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const tx = this.store.beginTransaction('readonly'), node = yield this.findINode(tx, p), data = yield tx.get(node.id);
+            if (!node.toStats().hasAccess(flag.getMode(), cred)) {
+                throw ApiError.EACCES(p);
+            }
+            if (data === undefined) {
+                throw ApiError.ENOENT(p);
+            }
+            return new AsyncKeyValueFile(this, p, flag, node.toStats(), data);
+        });
+    }
+    unlink(p, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.removeEntry(p, false, cred);
+        });
+    }
+    rmdir(p, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Check first if directory is empty.
+            const list = yield this.readdir(p, cred);
+            if (list.length > 0) {
+                throw ApiError.ENOTEMPTY(p);
+            }
+            yield this.removeEntry(p, true, cred);
+        });
+    }
+    mkdir(p, mode, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const tx = this.store.beginTransaction('readwrite'), data = Buffer.from('{}');
+            yield this.commitNewFile(tx, p, FileType.DIRECTORY, mode, cred, data);
+        });
+    }
+    readdir(p, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const tx = this.store.beginTransaction('readonly');
+            const node = yield this.findINode(tx, p);
+            if (!node.toStats().hasAccess(R_OK, cred)) {
+                throw ApiError.EACCES(p);
+            }
+            return Object.keys(yield this.getDirListing(tx, p, node));
+        });
+    }
+    chmod(p, mode, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const fd = yield this.openFile(p, FileFlag.getFileFlag('r+'), cred);
+            yield fd.chmod(mode);
+        });
+    }
+    chown(p, new_uid, new_gid, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const fd = yield this.openFile(p, FileFlag.getFileFlag('r+'), cred);
+            yield fd.chown(new_uid, new_gid);
+        });
+    }
+    _sync(p, data, stats) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // @todo Ensure mtime updates properly, and use that to determine if a data
+            //       update is required.
+            const tx = this.store.beginTransaction('readwrite'), 
+            // We use the _findInode helper because we actually need the INode id.
+            fileInodeId = yield this._findINode(tx, path.dirname(p), path.basename(p)), fileInode = yield this.getINode(tx, p, fileInodeId), inodeChanged = fileInode.update(stats);
+            try {
+                // Sync data.
+                yield tx.put(fileInode.id, data, true);
+                // Sync metadata.
+                if (inodeChanged) {
+                    yield tx.put(fileInodeId, fileInode.toBuffer(), true);
+                }
+            }
+            catch (e) {
+                yield tx.abort();
+                throw e;
+            }
+            yield tx.commit();
+        });
+    }
+    /**
+     * Checks if the root directory exists. Creates it if it doesn't.
+     */
+    makeRootDirectory() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const tx = this.store.beginTransaction('readwrite');
+            if ((yield tx.get(ROOT_NODE_ID)) === undefined) {
+                // Create new inode.
+                const currTime = new Date().getTime(), 
+                // Mode 0666, owned by root:root
+                dirInode = new Inode(randomUUID(), 4096, 511 | FileType.DIRECTORY, currTime, currTime, currTime, 0, 0);
+                // If the root doesn't exist, the first random ID shouldn't exist,
+                // either.
+                yield tx.put(dirInode.id, getEmptyDirNode(), false);
+                yield tx.put(ROOT_NODE_ID, dirInode.toBuffer(), false);
+                yield tx.commit();
+            }
+        });
+    }
+    /**
+     * 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.
+     */
+    _findINode(tx, parent, filename, visited = new Set()) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const currentPath = path.posix.join(parent, filename);
+            if (visited.has(currentPath)) {
+                throw new ApiError(ErrorCode.EIO, 'Infinite loop detected while finding inode', currentPath);
+            }
+            visited.add(currentPath);
+            if (this._cache) {
+                const id = this._cache.get(currentPath);
+                if (id) {
+                    return id;
+                }
+            }
+            if (parent === '/') {
+                if (filename === '') {
+                    // BASE CASE #1: Return the root's ID.
+                    if (this._cache) {
+                        this._cache.set(currentPath, ROOT_NODE_ID);
+                    }
+                    return ROOT_NODE_ID;
+                }
+                else {
+                    // BASE CASE #2: Find the item in the root node.
+                    const inode = yield this.getINode(tx, parent, ROOT_NODE_ID);
+                    const dirList = yield this.getDirListing(tx, parent, inode);
+                    if (dirList[filename]) {
+                        const id = dirList[filename];
+                        if (this._cache) {
+                            this._cache.set(currentPath, id);
+                        }
+                        return id;
+                    }
+                    else {
+                        throw ApiError.ENOENT(path.resolve(parent, filename));
+                    }
+                }
+            }
+            else {
+                // Get the parent directory's INode, and find the file in its directory
+                // listing.
+                const inode = yield this.findINode(tx, parent, visited);
+                const dirList = yield this.getDirListing(tx, parent, inode);
+                if (dirList[filename]) {
+                    const id = dirList[filename];
+                    if (this._cache) {
+                        this._cache.set(currentPath, id);
+                    }
+                    return id;
+                }
+                else {
+                    throw ApiError.ENOENT(path.resolve(parent, filename));
+                }
+            }
+        });
+    }
+    /**
+     * Finds the Inode of the given path.
+     * @param p The path to look up.
+     * @todo memoize/cache
+     */
+    findINode(tx, p, visited = new Set()) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const id = yield this._findINode(tx, path.dirname(p), path.basename(p), visited);
+            return this.getINode(tx, p, id);
+        });
+    }
+    /**
+     * Given the ID of a node, retrieves the corresponding Inode.
+     * @param tx The transaction to use.
+     * @param p The corresponding path to the file (used for error messages).
+     * @param id The ID to look up.
+     */
+    getINode(tx, p, id) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const data = yield tx.get(id);
+            if (!data) {
+                throw ApiError.ENOENT(p);
+            }
+            return Inode.fromBuffer(data);
+        });
+    }
+    /**
+     * Given the Inode of a directory, retrieves the corresponding directory
+     * listing.
+     */
+    getDirListing(tx, p, inode) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!inode.isDirectory()) {
+                throw ApiError.ENOTDIR(p);
+            }
+            const data = yield tx.get(inode.id);
+            try {
+                return JSON.parse(data.toString());
+            }
+            catch (e) {
+                // Occurs when data is undefined, or corresponds to something other
+                // than a directory listing. The latter should never occur unless
+                // the file system is corrupted.
+                throw ApiError.ENOENT(p);
+            }
+        });
+    }
+    /**
+     * Adds a new node under a random ID. Retries 5 times before giving up in
+     * the exceedingly unlikely chance that we try to reuse a random GUID.
+     */
+    addNewNode(tx, data) {
+        return __awaiter(this, void 0, void 0, function* () {
+            let retries = 0;
+            const reroll = () => __awaiter(this, void 0, void 0, function* () {
+                if (++retries === 5) {
+                    // Max retries hit. Return with an error.
+                    throw new ApiError(ErrorCode.EIO, 'Unable to commit data to key-value store.');
+                }
+                else {
+                    // Try again.
+                    const currId = randomUUID();
+                    const committed = yield tx.put(currId, data, false);
+                    if (!committed) {
+                        return reroll();
+                    }
+                    else {
+                        return currId;
+                    }
+                }
+            });
+            return reroll();
+        });
+    }
+    /**
+     * 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 p 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.
+     */
+    commitNewFile(tx, p, type, mode, cred, data) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const parentDir = path.dirname(p), fname = path.basename(p), parentNode = yield this.findINode(tx, parentDir), dirListing = yield this.getDirListing(tx, parentDir, parentNode), currTime = new Date().getTime();
+            //Check that the creater has correct access
+            if (!parentNode.toStats().hasAccess(W_OK, cred)) {
+                throw ApiError.EACCES(p);
+            }
+            // Invariant: The root always exists.
+            // If we don't check this prior to taking steps below, we will create a
+            // file with name '' in root should p == '/'.
+            if (p === '/') {
+                throw ApiError.EEXIST(p);
+            }
+            // Check if file already exists.
+            if (dirListing[fname]) {
+                yield tx.abort();
+                throw ApiError.EEXIST(p);
+            }
+            try {
+                // Commit data.
+                const dataId = yield this.addNewNode(tx, data);
+                const fileNode = new Inode(dataId, data.length, mode | type, currTime, currTime, currTime, cred.uid, cred.gid);
+                // Commit file node.
+                const fileNodeId = yield this.addNewNode(tx, fileNode.toBuffer());
+                // Update and commit parent directory listing.
+                dirListing[fname] = fileNodeId;
+                yield tx.put(parentNode.id, Buffer.from(JSON.stringify(dirListing)), true);
+                yield tx.commit();
+                return fileNode;
+            }
+            catch (e) {
+                tx.abort();
+                throw e;
+            }
+        });
+    }
+    /**
+     * Remove all traces of the given path from the file system.
+     * @param p The path to remove from the file system.
+     * @param isDir Does the path belong to a directory, or a file?
+     * @todo Update mtime.
+     */
+    /**
+     * Remove all traces of the given path from the file system.
+     * @param p The path to remove from the file system.
+     * @param isDir Does the path belong to a directory, or a file?
+     * @todo Update mtime.
+     */
+    removeEntry(p, isDir, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this._cache) {
+                this._cache.remove(p);
+            }
+            const tx = this.store.beginTransaction('readwrite'), parent = path.dirname(p), parentNode = yield this.findINode(tx, parent), parentListing = yield this.getDirListing(tx, parent, parentNode), fileName = path.basename(p);
+            if (!parentListing[fileName]) {
+                throw ApiError.ENOENT(p);
+            }
+            const fileNodeId = parentListing[fileName];
+            // Get file inode.
+            const fileNode = yield this.getINode(tx, p, fileNodeId);
+            if (!fileNode.toStats().hasAccess(W_OK, cred)) {
+                throw ApiError.EACCES(p);
+            }
+            // Remove from directory listing of parent.
+            delete parentListing[fileName];
+            if (!isDir && fileNode.isDirectory()) {
+                throw ApiError.EISDIR(p);
+            }
+            else if (isDir && !fileNode.isDirectory()) {
+                throw ApiError.ENOTDIR(p);
+            }
+            try {
+                // Delete data.
+                yield tx.del(fileNode.id);
+                // Delete node.
+                yield tx.del(fileNodeId);
+                // Update directory listing.
+                yield tx.put(parentNode.id, Buffer.from(JSON.stringify(parentListing)), true);
+            }
+            catch (e) {
+                yield tx.abort();
+                throw e;
+            }
+            // Success.
+            yield tx.commit();
+        });
+    }
+}

package/dist/backends/FolderAdapter.d.ts

@@ -0,0 +1,52 @@
+import { BaseFileSystem, type FileSystem } from '../filesystem';
+import { type BackendOptions } from './backend';
+export declare namespace FolderAdapter {
+    /**
+     * Configuration options for a FolderAdapter file system.
+     */
+    interface Options {
+        folder: string;
+        wrapped: FileSystem;
+    }
+}
+/**
+ * The FolderAdapter file system wraps a file system, and scopes all interactions to a subfolder of that file system.
+ *
+ * Example: Given a file system `foo` with folder `bar` and file `bar/baz`...
+ *
+ * ```javascript
+ * ZenFS.configure({
+ *   fs: "FolderAdapter",
+ *   options: {
+ *     folder: "bar",
+ *     wrapped: foo
+ *   }
+ * }, function(e) {
+ *   var fs = ZenFS.BFSRequire('fs');
+ *   fs.readdirSync('/'); // ['baz']
+ * });
+ * ```
+ */
+export declare class FolderAdapter extends BaseFileSystem {
+    static readonly Name = "FolderAdapter";
+    static Create: any;
+    static readonly Options: BackendOptions;
+    static isAvailable(): boolean;
+    _wrapped: FileSystem;
+    _folder: string;
+    constructor({ folder, wrapped }: FolderAdapter.Options);
+    get metadata(): {
+        supportsLinks: boolean;
+        name: string;
+        readonly: boolean;
+        synchronous: boolean;
+        supportsProperties: boolean;
+        totalSpace: number;
+        freeSpace: number;
+    };
+    /**
+     * Initialize the file system. Ensures that the wrapped file system
+     * has the given folder.
+     */
+    private _initialize;
+}