@zenfs/core 0.0.1

package/dist/index.js

@@ -0,0 +1,113 @@
+/**
+ * ZenFS's main module. This is exposed in the browser via the ZenFS global.
+ */
+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 fs from './emulation/fs';
+import { FileSystem } from './filesystem';
+import { backends } from './backends';
+import { ErrorCode, ApiError } from './ApiError';
+import { Cred } from './cred';
+import * as process from 'process';
+import { setCred } from './emulation/shared';
+if (process && process['initializeTTYs']) {
+    process['initializeTTYs']();
+}
+/**
+ * Initializes ZenFS with the given file systems.
+ */
+export function initialize(mounts, uid = 0, gid = 0) {
+    setCred(new Cred(uid, gid, uid, gid, uid, gid));
+    return fs.initialize(mounts);
+}
+function _configure(config) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if ('fs' in config || config instanceof FileSystem) {
+            // single FS
+            config = { '/': config };
+        }
+        for (let [point, value] of Object.entries(config)) {
+            if (typeof value == 'number') {
+                //should never happen
+                continue;
+            }
+            point = point.toString(); // so linting stops complaining that point should be declared with const, which can't be done since value is assigned to
+            if (value instanceof FileSystem) {
+                continue;
+            }
+            if (typeof value == 'string') {
+                value = { fs: value };
+            }
+            config[point] = yield getFileSystem(value);
+        }
+        return initialize(config);
+    });
+}
+export function configure(config, cb) {
+    // Promise version
+    if (typeof cb != 'function') {
+        return _configure(config);
+    }
+    // Callback version
+    _configure(config)
+        .then(() => cb())
+        .catch(err => cb(err));
+    return;
+}
+function _getFileSystem({ fs: fsName, options = {} }) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (!fsName) {
+            throw new ApiError(ErrorCode.EPERM, 'Missing "fs" property on configuration object.');
+        }
+        if (typeof options !== 'object' || options === null) {
+            throw new ApiError(ErrorCode.EINVAL, 'Invalid "options" property on configuration object.');
+        }
+        const props = Object.keys(options).filter(k => k != 'fs');
+        for (const prop of props) {
+            const opt = options[prop];
+            if (opt === null || typeof opt !== 'object' || !('fs' in opt)) {
+                continue;
+            }
+            const fs = yield _getFileSystem(opt);
+            options[prop] = fs;
+        }
+        const fsc = backends[fsName];
+        if (!fsc) {
+            throw new ApiError(ErrorCode.EPERM, `File system ${fsName} is not available in ZenFS.`);
+        }
+        else {
+            return fsc.Create(options);
+        }
+    });
+}
+export function getFileSystem(config, cb) {
+    // Promise version
+    if (typeof cb != 'function') {
+        return _getFileSystem(config);
+    }
+    // Callback version
+    _getFileSystem(config)
+        .then(fs => cb(null, fs))
+        .catch(err => cb(err));
+    return;
+}
+export * from './backends';
+export * from './backends/AsyncStore';
+export * from './backends/SyncStore';
+export * from './ApiError';
+export * from './cred';
+export * from './file';
+export * from './filesystem';
+export * from './inode';
+export * from './mutex';
+export * from './stats';
+export * from './utils';
+export { fs };
+export default fs;

package/dist/inode.d.ts

@@ -0,0 +1,51 @@
+/// <reference types="node" />
+import { Stats } from './stats';
+/**
+ * Generic inode definition that can easily be serialized.
+ */
+export default class Inode {
+    id: string;
+    size: number;
+    mode: number;
+    atime: number;
+    mtime: number;
+    ctime: number;
+    uid: number;
+    gid: number;
+    /**
+     * Converts the buffer into an Inode.
+     */
+    static fromBuffer(buffer: Buffer): Inode;
+    constructor(id: string, size: number, mode: number, atime: number, mtime: number, ctime: number, uid: number, gid: number);
+    /**
+     * Handy function that converts the Inode to a Node Stats object.
+     */
+    toStats(): Stats;
+    /**
+     * Get the size of this Inode, in bytes.
+     */
+    getSize(): number;
+    /**
+     * Writes the inode into the start of the buffer.
+     */
+    toBuffer(buff?: Buffer): Buffer;
+    /**
+     * Updates the Inode using information from the stats object. Used by file
+     * systems at sync time, e.g.:
+     * - Program opens file and gets a File object.
+     * - Program mutates file. File object is responsible for maintaining
+     *   metadata changes locally -- typically in a Stats object.
+     * - Program closes file. File object's metadata changes are synced with the
+     *   file system.
+     * @return True if any changes have occurred.
+     */
+    update(stats: Stats): boolean;
+    /**
+     * @return [Boolean] True if this item is a file.
+     */
+    isFile(): boolean;
+    /**
+     * @return [Boolean] True if this item is a directory.
+     */
+    isDirectory(): boolean;
+}

package/dist/inode.js

@@ -0,0 +1,112 @@
+import { Stats, FileType } from './stats';
+import { Buffer } from 'buffer';
+/**
+ * Generic inode definition that can easily be serialized.
+ */
+export default class Inode {
+    /**
+     * Converts the buffer into an Inode.
+     */
+    static fromBuffer(buffer) {
+        if (buffer === undefined) {
+            throw new Error('NO');
+        }
+        return new Inode(buffer.toString('ascii', 38), buffer.readUInt32LE(0), buffer.readUInt16LE(4), buffer.readDoubleLE(6), buffer.readDoubleLE(14), buffer.readDoubleLE(22), buffer.readUInt32LE(30), buffer.readUInt32LE(34));
+    }
+    constructor(id, size, mode, atime, mtime, ctime, uid, gid) {
+        this.id = id;
+        this.size = size;
+        this.mode = mode;
+        this.atime = atime;
+        this.mtime = mtime;
+        this.ctime = ctime;
+        this.uid = uid;
+        this.gid = gid;
+    }
+    /**
+     * Handy function that converts the Inode to a Node Stats object.
+     */
+    toStats() {
+        return new Stats((this.mode & 0xf000) === FileType.DIRECTORY ? FileType.DIRECTORY : FileType.FILE, this.size, this.mode, this.atime, this.mtime, this.ctime, this.uid, this.gid);
+    }
+    /**
+     * Get the size of this Inode, in bytes.
+     */
+    getSize() {
+        // ASSUMPTION: ID is ASCII (1 byte per char).
+        return 38 + this.id.length;
+    }
+    /**
+     * Writes the inode into the start of the buffer.
+     */
+    toBuffer(buff = Buffer.alloc(this.getSize())) {
+        buff.writeUInt32LE(this.size, 0);
+        buff.writeUInt16LE(this.mode, 4);
+        buff.writeDoubleLE(this.atime, 6);
+        buff.writeDoubleLE(this.mtime, 14);
+        buff.writeDoubleLE(this.ctime, 22);
+        buff.writeUInt32LE(this.uid, 30);
+        buff.writeUInt32LE(this.gid, 34);
+        buff.write(this.id, 38, this.id.length, 'ascii');
+        return buff;
+    }
+    /**
+     * Updates the Inode using information from the stats object. Used by file
+     * systems at sync time, e.g.:
+     * - Program opens file and gets a File object.
+     * - Program mutates file. File object is responsible for maintaining
+     *   metadata changes locally -- typically in a Stats object.
+     * - Program closes file. File object's metadata changes are synced with the
+     *   file system.
+     * @return True if any changes have occurred.
+     */
+    update(stats) {
+        let hasChanged = false;
+        if (this.size !== stats.size) {
+            this.size = stats.size;
+            hasChanged = true;
+        }
+        if (this.mode !== stats.mode) {
+            this.mode = stats.mode;
+            hasChanged = true;
+        }
+        const atimeMs = stats.atime.getTime();
+        if (this.atime !== atimeMs) {
+            this.atime = atimeMs;
+            hasChanged = true;
+        }
+        const mtimeMs = stats.mtime.getTime();
+        if (this.mtime !== mtimeMs) {
+            this.mtime = mtimeMs;
+            hasChanged = true;
+        }
+        const ctimeMs = stats.ctime.getTime();
+        if (this.ctime !== ctimeMs) {
+            this.ctime = ctimeMs;
+            hasChanged = true;
+        }
+        if (this.uid !== stats.uid) {
+            this.uid = stats.uid;
+            hasChanged = true;
+        }
+        if (this.uid !== stats.uid) {
+            this.uid = stats.uid;
+            hasChanged = true;
+        }
+        return hasChanged;
+    }
+    // XXX: Copied from Stats. Should reconcile these two into something more
+    //      compact.
+    /**
+     * @return [Boolean] True if this item is a file.
+     */
+    isFile() {
+        return (this.mode & 0xf000) === FileType.FILE;
+    }
+    /**
+     * @return [Boolean] True if this item is a directory.
+     */
+    isDirectory() {
+        return (this.mode & 0xf000) === FileType.DIRECTORY;
+    }
+}

package/dist/mutex.d.ts

@@ -0,0 +1,12 @@
+export type MutexCallback = () => void;
+/**
+ * Non-recursive mutex
+ * @internal
+ */
+export default class Mutex {
+    private _locks;
+    lock(path: string): Promise<void>;
+    unlock(path: string): void;
+    tryLock(path: string): boolean;
+    isLocked(path: string): boolean;
+}

package/dist/mutex.js

@@ -0,0 +1,48 @@
+/**
+ * Non-recursive mutex
+ * @internal
+ */
+export default class Mutex {
+    constructor() {
+        this._locks = new Map();
+    }
+    lock(path) {
+        return new Promise(resolve => {
+            if (this._locks.has(path)) {
+                this._locks.get(path).push(resolve);
+            }
+            else {
+                this._locks.set(path, []);
+            }
+        });
+    }
+    unlock(path) {
+        if (!this._locks.has(path)) {
+            throw new Error('unlock of a non-locked mutex');
+        }
+        const next = this._locks.get(path).shift();
+        /*
+            don't unlock - we want to queue up next for the
+            end of the current task execution, but we don't
+            want it to be called inline with whatever the
+            current stack is.  This way we still get the nice
+            behavior that an unlock immediately followed by a
+            lock won't cause starvation.
+        */
+        if (next) {
+            setTimeout(next, 0);
+            return;
+        }
+        this._locks.delete(path);
+    }
+    tryLock(path) {
+        if (this._locks.has(path)) {
+            return false;
+        }
+        this._locks.set(path, []);
+        return true;
+    }
+    isLocked(path) {
+        return this._locks.has(path);
+    }
+}

package/dist/stats.d.ts

@@ -0,0 +1,98 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import type { StatsBase } from 'fs';
+import { Cred } from './cred';
+/**
+ * Indicates the type of the given file. Applied to 'mode'.
+ */
+export declare enum FileType {
+    FILE,
+    DIRECTORY,
+    SYMLINK
+}
+/**
+ * Implementation of Node's `Stats`.
+ *
+ * Attribute descriptions are from `man 2 stat'
+ * @see http://nodejs.org/api/fs.html#fs_class_fs_stats
+ * @see http://man7.org/linux/man-pages/man2/stat.2.html
+ */
+export declare class Stats implements StatsBase<number> {
+    static fromBuffer(buffer: Buffer): Stats;
+    /**
+     * Clones the stats object.
+     */
+    static clone(s: Stats): Stats;
+    blocks: number;
+    mode: number;
+    dev: number;
+    ino: number;
+    rdev: number;
+    nlink: number;
+    blksize: number;
+    uid: number;
+    gid: number;
+    fileData: Buffer | null;
+    atimeMs: number;
+    mtimeMs: number;
+    ctimeMs: number;
+    birthtimeMs: number;
+    size: number;
+    get atime(): Date;
+    get mtime(): Date;
+    get ctime(): Date;
+    get birthtime(): Date;
+    /**
+     * Provides information about a particular entry in the file system.
+     * @param itemType Type of the item (FILE, DIRECTORY, SYMLINK, or SOCKET)
+     * @param size Size of the item in bytes. For directories/symlinks,
+     *   this is normally the size of the struct that represents the item.
+     * @param mode Unix-style file mode (e.g. 0o644)
+     * @param atimeMs time of last access, in milliseconds since epoch
+     * @param mtimeMs time of last modification, in milliseconds since epoch
+     * @param ctimeMs time of last time file status was changed, in milliseconds since epoch
+     * @param uid the id of the user that owns the file
+     * @param gid the id of the group that owns the file
+     * @param birthtimeMs time of file creation, in milliseconds since epoch
+     */
+    constructor(itemType: FileType, size: number, mode?: number, atimeMs?: number, mtimeMs?: number, ctimeMs?: number, uid?: number, gid?: number, birthtimeMs?: number);
+    toBuffer(): Buffer;
+    /**
+     * @return [Boolean] True if this item is a file.
+     */
+    isFile(): boolean;
+    /**
+     * @return [Boolean] True if this item is a directory.
+     */
+    isDirectory(): boolean;
+    /**
+     * @return [Boolean] True if this item is a symbolic link (only valid through lstat)
+     */
+    isSymbolicLink(): boolean;
+    /**
+     * Checks if a given user/group has access to this item
+     * @param mode The request access as 4 bits (unused, read, write, execute)
+     * @param uid The requesting UID
+     * @param gid The requesting GID
+     * @returns [Boolean] True if the request has access, false if the request does not
+     */
+    hasAccess(mode: number, cred: Cred): boolean;
+    /**
+     * Convert the current stats object into a cred object
+     */
+    getCred(uid?: number, gid?: number): Cred;
+    /**
+     * Change the mode of the file. We use this helper function to prevent messing
+     * up the type of the file, which is encoded in mode.
+     */
+    chmod(mode: number): void;
+    /**
+     * Change the owner user/group of the file.
+     * This function makes sure it is a valid UID/GID (that is, a 32 unsigned int)
+     */
+    chown(uid: number, gid: number): void;
+    isSocket(): boolean;
+    isBlockDevice(): boolean;
+    isCharacterDevice(): boolean;
+    isFIFO(): boolean;
+}

package/dist/stats.js

@@ -0,0 +1,226 @@
+import { Cred } from './cred';
+import { Buffer } from 'buffer';
+import { S_IFDIR, S_IFLNK, S_IFMT, S_IFREG } from './emulation/constants';
+/**
+ * Indicates the type of the given file. Applied to 'mode'.
+ */
+export var FileType;
+(function (FileType) {
+    FileType[FileType["FILE"] = S_IFREG] = "FILE";
+    FileType[FileType["DIRECTORY"] = S_IFDIR] = "DIRECTORY";
+    FileType[FileType["SYMLINK"] = S_IFLNK] = "SYMLINK";
+})(FileType || (FileType = {}));
+/**
+ * Implementation of Node's `Stats`.
+ *
+ * Attribute descriptions are from `man 2 stat'
+ * @see http://nodejs.org/api/fs.html#fs_class_fs_stats
+ * @see http://man7.org/linux/man-pages/man2/stat.2.html
+ */
+export class Stats {
+    static fromBuffer(buffer) {
+        const size = buffer.readUInt32LE(0), mode = buffer.readUInt32LE(4), atime = buffer.readDoubleLE(8), mtime = buffer.readDoubleLE(16), ctime = buffer.readDoubleLE(24), uid = buffer.readUInt32LE(32), gid = buffer.readUInt32LE(36);
+        return new Stats(mode & S_IFMT, size, mode & ~S_IFMT, atime, mtime, ctime, uid, gid);
+    }
+    /**
+     * Clones the stats object.
+     */
+    static clone(s) {
+        return new Stats(s.mode & S_IFMT, s.size, s.mode & ~S_IFMT, s.atimeMs, s.mtimeMs, s.ctimeMs, s.uid, s.gid, s.birthtimeMs);
+    }
+    get atime() {
+        return new Date(this.atimeMs);
+    }
+    get mtime() {
+        return new Date(this.mtimeMs);
+    }
+    get ctime() {
+        return new Date(this.ctimeMs);
+    }
+    get birthtime() {
+        return new Date(this.birthtimeMs);
+    }
+    /**
+     * Provides information about a particular entry in the file system.
+     * @param itemType Type of the item (FILE, DIRECTORY, SYMLINK, or SOCKET)
+     * @param size Size of the item in bytes. For directories/symlinks,
+     *   this is normally the size of the struct that represents the item.
+     * @param mode Unix-style file mode (e.g. 0o644)
+     * @param atimeMs time of last access, in milliseconds since epoch
+     * @param mtimeMs time of last modification, in milliseconds since epoch
+     * @param ctimeMs time of last time file status was changed, in milliseconds since epoch
+     * @param uid the id of the user that owns the file
+     * @param gid the id of the group that owns the file
+     * @param birthtimeMs time of file creation, in milliseconds since epoch
+     */
+    constructor(itemType, size, mode, atimeMs, mtimeMs, ctimeMs, uid, gid, birthtimeMs) {
+        // ID of device containing file
+        this.dev = 0;
+        // inode number
+        this.ino = 0;
+        // device ID (if special file)
+        this.rdev = 0;
+        // number of hard links
+        this.nlink = 1;
+        // blocksize for file system I/O
+        this.blksize = 4096;
+        // user ID of owner
+        this.uid = 0;
+        // group ID of owner
+        this.gid = 0;
+        // Some file systems stash data on stats objects.
+        this.fileData = null;
+        this.size = size;
+        let currentTime = 0;
+        if (typeof atimeMs !== 'number') {
+            currentTime = Date.now();
+            atimeMs = currentTime;
+        }
+        if (typeof mtimeMs !== 'number') {
+            if (!currentTime) {
+                currentTime = Date.now();
+            }
+            mtimeMs = currentTime;
+        }
+        if (typeof ctimeMs !== 'number') {
+            if (!currentTime) {
+                currentTime = Date.now();
+            }
+            ctimeMs = currentTime;
+        }
+        if (typeof birthtimeMs !== 'number') {
+            if (!currentTime) {
+                currentTime = Date.now();
+            }
+            birthtimeMs = currentTime;
+        }
+        if (typeof uid !== 'number') {
+            uid = 0;
+        }
+        if (typeof gid !== 'number') {
+            gid = 0;
+        }
+        this.atimeMs = atimeMs;
+        this.ctimeMs = ctimeMs;
+        this.mtimeMs = mtimeMs;
+        this.birthtimeMs = birthtimeMs;
+        if (!mode) {
+            switch (itemType) {
+                case FileType.FILE:
+                    this.mode = 0o644;
+                    break;
+                case FileType.DIRECTORY:
+                default:
+                    this.mode = 0o777;
+            }
+        }
+        else {
+            this.mode = mode;
+        }
+        // number of 512B blocks allocated
+        this.blocks = Math.ceil(size / 512);
+        // Check if mode also includes top-most bits, which indicate the file's
+        // type.
+        if ((this.mode & S_IFMT) == 0) {
+            this.mode |= itemType;
+        }
+    }
+    toBuffer() {
+        const buffer = Buffer.alloc(32);
+        buffer.writeUInt32LE(this.size, 0);
+        buffer.writeUInt32LE(this.mode, 4);
+        buffer.writeDoubleLE(this.atime.getTime(), 8);
+        buffer.writeDoubleLE(this.mtime.getTime(), 16);
+        buffer.writeDoubleLE(this.ctime.getTime(), 24);
+        buffer.writeUInt32LE(this.uid, 32);
+        buffer.writeUInt32LE(this.gid, 36);
+        return buffer;
+    }
+    /**
+     * @return [Boolean] True if this item is a file.
+     */
+    isFile() {
+        return (this.mode & S_IFMT) === S_IFREG;
+    }
+    /**
+     * @return [Boolean] True if this item is a directory.
+     */
+    isDirectory() {
+        return (this.mode & S_IFMT) === S_IFDIR;
+    }
+    /**
+     * @return [Boolean] True if this item is a symbolic link (only valid through lstat)
+     */
+    isSymbolicLink() {
+        return (this.mode & S_IFMT) === S_IFLNK;
+    }
+    /**
+     * Checks if a given user/group has access to this item
+     * @param mode The request access as 4 bits (unused, read, write, execute)
+     * @param uid The requesting UID
+     * @param gid The requesting GID
+     * @returns [Boolean] True if the request has access, false if the request does not
+     */
+    hasAccess(mode, cred) {
+        if (cred.euid === 0 || cred.egid === 0) {
+            //Running as root
+            return true;
+        }
+        const perms = this.mode & ~S_IFMT;
+        let uMode = 0xf, gMode = 0xf, wMode = 0xf;
+        if (cred.euid == this.uid) {
+            const uPerms = (0xf00 & perms) >> 8;
+            uMode = (mode ^ uPerms) & mode;
+        }
+        if (cred.egid == this.gid) {
+            const gPerms = (0xf0 & perms) >> 4;
+            gMode = (mode ^ gPerms) & mode;
+        }
+        const wPerms = 0xf & perms;
+        wMode = (mode ^ wPerms) & mode;
+        /*
+        Result = 0b0xxx (read, write, execute)
+        If any bits are set that means the request does not have that permission.
+    */
+        const result = uMode & gMode & wMode;
+        return !result;
+    }
+    /**
+     * Convert the current stats object into a cred object
+     */
+    getCred(uid = this.uid, gid = this.gid) {
+        return new Cred(uid, gid, this.uid, this.gid, uid, gid);
+    }
+    /**
+     * Change the mode of the file. We use this helper function to prevent messing
+     * up the type of the file, which is encoded in mode.
+     */
+    chmod(mode) {
+        this.mode = (this.mode & S_IFMT) | mode;
+    }
+    /**
+     * Change the owner user/group of the file.
+     * This function makes sure it is a valid UID/GID (that is, a 32 unsigned int)
+     */
+    chown(uid, gid) {
+        if (!isNaN(+uid) && 0 <= +uid && +uid < Math.pow(2, 32)) {
+            this.uid = uid;
+        }
+        if (!isNaN(+gid) && 0 <= +gid && +gid < Math.pow(2, 32)) {
+            this.gid = gid;
+        }
+    }
+    // We don't support the following types of files.
+    isSocket() {
+        return false;
+    }
+    isBlockDevice() {
+        return false;
+    }
+    isCharacterDevice() {
+        return false;
+    }
+    isFIFO() {
+        return false;
+    }
+}