@zenfs/core 0.0.1

package/dist/backends/AsyncMirror.js

@@ -0,0 +1,252 @@
+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());
+    });
+};
+var _a;
+import { SynchronousFileSystem } from '../filesystem';
+import { ApiError, ErrorCode } from '../ApiError';
+import { FileFlag, PreloadFile } from '../file';
+import * as path from 'path';
+import { Cred } from '../cred';
+import { CreateBackend } from './backend';
+/**
+ * We define our own file to interpose on syncSync() for mirroring purposes.
+ */
+class MirrorFile extends PreloadFile {
+    constructor(fs, path, flag, stat, data) {
+        super(fs, path, flag, stat, data);
+    }
+    syncSync() {
+        if (this.isDirty()) {
+            this._fs._syncSync(this);
+            this.resetDirty();
+        }
+    }
+    closeSync() {
+        this.syncSync();
+    }
+}
+/**
+ * AsyncMirrorFS mirrors a synchronous filesystem into an asynchronous filesystem
+ * by:
+ *
+ * * Performing operations over the in-memory copy, while asynchronously pipelining them
+ *   to the backing store.
+ * * During application loading, the contents of the async file system can be reloaded into
+ *   the synchronous store, if desired.
+ *
+ * The two stores will be kept in sync. The most common use-case is to pair a synchronous
+ * in-memory filesystem with an asynchronous backing store.
+ *
+ * Example: Mirroring an IndexedDB file system to an in memory file system. Now, you can use
+ * IndexedDB synchronously.
+ *
+ * ```javascript
+ * ZenFS.configure({
+ *   fs: "AsyncMirror",
+ *   options: {
+ *     sync: { fs: "InMemory" },
+ *     async: { fs: "IndexedDB" }
+ *   }
+ * }, function(e) {
+ *   // ZenFS is initialized and ready-to-use!
+ * });
+ * ```
+ *
+ * Or, alternatively:
+ *
+ * ```javascript
+ * ZenFS.Backend.IndexedDB.Create(function(e, idbfs) {
+ *   ZenFS.Backend.InMemory.Create(function(e, inMemory) {
+ *     ZenFS.Backend.AsyncMirror({
+ *       sync: inMemory, async: idbfs
+ *     }, function(e, mirrored) {
+ *       ZenFS.initialize(mirrored);
+ *     });
+ *   });
+ * });
+ * ```
+ */
+export class AsyncMirror extends SynchronousFileSystem {
+    static isAvailable() {
+        return true;
+    }
+    /**
+     *
+     * Mirrors the synchronous file system into the asynchronous file system.
+     *
+     * @param sync The synchronous file system to mirror the asynchronous file system to.
+     * @param async The asynchronous file system to mirror.
+     */
+    constructor({ sync, async }) {
+        super();
+        /**
+         * Queue of pending asynchronous operations.
+         */
+        this._queue = [];
+        this._queueRunning = false;
+        this._isInitialized = false;
+        this._initializeCallbacks = [];
+        this._sync = sync;
+        this._async = async;
+        this._ready = this._initialize();
+    }
+    get metadata() {
+        return Object.assign(Object.assign({}, super.metadata), { name: AsyncMirror.Name, synchronous: true, supportsProperties: this._sync.metadata.supportsProperties && this._async.metadata.supportsProperties });
+    }
+    _syncSync(fd) {
+        const stats = fd.getStats();
+        this._sync.writeFileSync(fd.getPath(), fd.getBuffer(), null, FileFlag.getFileFlag('w'), stats.mode, stats.getCred(0, 0));
+        this.enqueueOp({
+            apiMethod: 'writeFile',
+            arguments: [fd.getPath(), fd.getBuffer(), null, fd.getFlag(), stats.mode, stats.getCred(0, 0)],
+        });
+    }
+    renameSync(oldPath, newPath, cred) {
+        this._sync.renameSync(oldPath, newPath, cred);
+        this.enqueueOp({
+            apiMethod: 'rename',
+            arguments: [oldPath, newPath, cred],
+        });
+    }
+    statSync(p, cred) {
+        return this._sync.statSync(p, cred);
+    }
+    openSync(p, flag, mode, cred) {
+        // Sanity check: Is this open/close permitted?
+        const fd = this._sync.openSync(p, flag, mode, cred);
+        fd.closeSync();
+        return new MirrorFile(this, p, flag, this._sync.statSync(p, cred), this._sync.readFileSync(p, null, FileFlag.getFileFlag('r'), cred));
+    }
+    unlinkSync(p, cred) {
+        this._sync.unlinkSync(p, cred);
+        this.enqueueOp({
+            apiMethod: 'unlink',
+            arguments: [p, cred],
+        });
+    }
+    rmdirSync(p, cred) {
+        this._sync.rmdirSync(p, cred);
+        this.enqueueOp({
+            apiMethod: 'rmdir',
+            arguments: [p, cred],
+        });
+    }
+    mkdirSync(p, mode, cred) {
+        this._sync.mkdirSync(p, mode, cred);
+        this.enqueueOp({
+            apiMethod: 'mkdir',
+            arguments: [p, mode, cred],
+        });
+    }
+    readdirSync(p, cred) {
+        return this._sync.readdirSync(p, cred);
+    }
+    existsSync(p, cred) {
+        return this._sync.existsSync(p, cred);
+    }
+    chmodSync(p, mode, cred) {
+        this._sync.chmodSync(p, mode, cred);
+        this.enqueueOp({
+            apiMethod: 'chmod',
+            arguments: [p, mode, cred],
+        });
+    }
+    chownSync(p, new_uid, new_gid, cred) {
+        this._sync.chownSync(p, new_uid, new_gid, cred);
+        this.enqueueOp({
+            apiMethod: 'chown',
+            arguments: [p, new_uid, new_gid, cred],
+        });
+    }
+    utimesSync(p, atime, mtime, cred) {
+        this._sync.utimesSync(p, atime, mtime, cred);
+        this.enqueueOp({
+            apiMethod: 'utimes',
+            arguments: [p, atime, mtime, cred],
+        });
+    }
+    /**
+     * Called once to load up files from async storage into sync storage.
+     */
+    _initialize() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this._isInitialized) {
+                // First call triggers initialization, the rest wait.
+                const copyDirectory = (p, mode) => __awaiter(this, void 0, void 0, function* () {
+                    if (p !== '/') {
+                        const stats = yield this._async.stat(p, Cred.Root);
+                        this._sync.mkdirSync(p, mode, stats.getCred());
+                    }
+                    const files = yield this._async.readdir(p, Cred.Root);
+                    for (const file of files) {
+                        yield copyItem(path.join(p, file));
+                    }
+                }), copyFile = (p, mode) => __awaiter(this, void 0, void 0, function* () {
+                    const data = yield this._async.readFile(p, null, FileFlag.getFileFlag('r'), Cred.Root);
+                    this._sync.writeFileSync(p, data, null, FileFlag.getFileFlag('w'), mode, Cred.Root);
+                }), copyItem = (p) => __awaiter(this, void 0, void 0, function* () {
+                    const stats = yield this._async.stat(p, Cred.Root);
+                    if (stats.isDirectory()) {
+                        yield copyDirectory(p, stats.mode);
+                    }
+                    else {
+                        yield copyFile(p, stats.mode);
+                    }
+                });
+                try {
+                    yield copyDirectory('/', 0);
+                    this._isInitialized = true;
+                }
+                catch (e) {
+                    this._isInitialized = false;
+                    throw e;
+                }
+            }
+            return this;
+        });
+    }
+    enqueueOp(op) {
+        this._queue.push(op);
+        if (!this._queueRunning) {
+            this._queueRunning = true;
+            const doNextOp = (err) => {
+                if (err) {
+                    throw new Error(`WARNING: File system has desynchronized. Received following error: ${err}\n$`);
+                }
+                if (this._queue.length > 0) {
+                    const op = this._queue.shift();
+                    op.arguments.push(doNextOp);
+                    this._async[op.apiMethod].apply(this._async, op.arguments);
+                }
+                else {
+                    this._queueRunning = false;
+                }
+            };
+            doNextOp();
+        }
+    }
+}
+_a = AsyncMirror;
+AsyncMirror.Name = 'AsyncMirror';
+AsyncMirror.Create = CreateBackend.bind(_a);
+AsyncMirror.Options = {
+    sync: {
+        type: 'object',
+        description: 'The synchronous file system to mirror the asynchronous file system to.',
+        validator: (v) => __awaiter(void 0, void 0, void 0, function* () {
+            if (!(v === null || v === void 0 ? void 0 : v.metadata.synchronous)) {
+                throw new ApiError(ErrorCode.EINVAL, `'sync' option must be a file system that supports synchronous operations`);
+            }
+        }),
+    },
+    async: {
+        type: 'object',
+        description: 'The asynchronous file system to mirror.',
+    },
+};

package/dist/backends/AsyncStore.d.ts

@@ -0,0 +1,166 @@
+/// <reference types="node" />
+import { Cred } from '../cred';
+import { PreloadFile, File, FileFlag } from '../file';
+import { BaseFileSystem } from '../filesystem';
+import { Stats } from '../stats';
+/**
+ * Represents an *asynchronous* key-value store.
+ */
+export interface AsyncKeyValueStore {
+    /**
+     * The name of the key-value store.
+     */
+    name(): string;
+    /**
+     * Empties the key-value store completely.
+     */
+    clear(): Promise<void>;
+    /**
+     * Begins a read-write transaction.
+     */
+    beginTransaction(type: 'readwrite'): AsyncKeyValueRWTransaction;
+    /**
+     * Begins a read-only transaction.
+     */
+    beginTransaction(type: 'readonly'): AsyncKeyValueROTransaction;
+    beginTransaction(type: string): AsyncKeyValueROTransaction;
+}
+/**
+ * Represents an asynchronous read-only transaction.
+ */
+export interface AsyncKeyValueROTransaction {
+    /**
+     * Retrieves the data at the given key.
+     * @param key The key to look under for data.
+     */
+    get(key: string): Promise<Buffer>;
+}
+/**
+ * Represents an asynchronous read-write transaction.
+ */
+export interface AsyncKeyValueRWTransaction extends AsyncKeyValueROTransaction {
+    /**
+     * Adds the data to the store under the given key. Overwrites any existing
+     * data.
+     * @param key The key to add the data under.
+     * @param data The data to add to the store.
+     * @param overwrite If 'true', overwrite any existing data. If 'false',
+     *   avoids writing the data if the key exists.
+     */
+    put(key: string, data: Buffer, overwrite: boolean): Promise<boolean>;
+    /**
+     * Deletes the data at the given key.
+     * @param key The key to delete from the store.
+     */
+    del(key: string): Promise<void>;
+    /**
+     * Commits the transaction.
+     */
+    commit(): Promise<void>;
+    /**
+     * Aborts and rolls back the transaction.
+     */
+    abort(): Promise<void>;
+}
+export declare class AsyncKeyValueFile extends PreloadFile<AsyncKeyValueFileSystem> implements File {
+    constructor(_fs: AsyncKeyValueFileSystem, _path: string, _flag: FileFlag, _stat: Stats, contents?: Buffer);
+    sync(): Promise<void>;
+    close(): Promise<void>;
+}
+/**
+ * An "Asynchronous key-value file system". Stores data to/retrieves data from
+ * an underlying asynchronous key-value store.
+ */
+export declare class AsyncKeyValueFileSystem extends BaseFileSystem {
+    static isAvailable(): boolean;
+    protected store: AsyncKeyValueStore;
+    private _cache;
+    constructor(cacheSize: number);
+    /**
+     * Initializes the file system. Typically called by subclasses' async
+     * constructors.
+     */
+    init(store: AsyncKeyValueStore): Promise<void>;
+    getName(): string;
+    isReadOnly(): boolean;
+    supportsSymlinks(): boolean;
+    supportsProps(): boolean;
+    supportsSynch(): boolean;
+    /**
+     * Delete all contents stored in the file system.
+     */
+    empty(): Promise<void>;
+    access(p: string, mode: number, cred: Cred): Promise<void>;
+    /**
+     * @todo Make rename compatible with the cache.
+     */
+    rename(oldPath: string, newPath: string, cred: Cred): Promise<void>;
+    stat(p: string, cred: Cred): Promise<Stats>;
+    createFile(p: string, flag: FileFlag, mode: number, cred: Cred): Promise<File>;
+    openFile(p: string, flag: FileFlag, cred: Cred): Promise<File>;
+    unlink(p: string, cred: Cred): Promise<void>;
+    rmdir(p: string, cred: Cred): Promise<void>;
+    mkdir(p: string, mode: number, cred: Cred): Promise<void>;
+    readdir(p: string, cred: Cred): Promise<string[]>;
+    chmod(p: string, mode: number, cred: Cred): Promise<void>;
+    chown(p: string, new_uid: number, new_gid: number, cred: Cred): Promise<void>;
+    _sync(p: string, data: Buffer, stats: Stats): Promise<void>;
+    /**
+     * Checks if the root directory exists. Creates it if it doesn't.
+     */
+    private makeRootDirectory;
+    /**
+     * 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;
+    /**
+     * Finds the Inode of the given path.
+     * @param p The path to look up.
+     * @todo memoize/cache
+     */
+    private findINode;
+    /**
+     * 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.
+     */
+    private getINode;
+    /**
+     * Given the Inode of a directory, retrieves the corresponding directory
+     * listing.
+     */
+    private getDirListing;
+    /**
+     * 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.
+     */
+    private addNewNode;
+    /**
+     * 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.
+     */
+    private commitNewFile;
+    /**
+     * 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.
+     */
+    private removeEntry;
+}