@zenfs/core 0.2.1 → 0.2.3

package/dist/backends/Overlay.js

@@ -0,0 +1,544 @@
+import { FileSystem } from '../filesystem.js';
+import { ApiError, ErrorCode } from '../ApiError.js';
+import { FileFlag, PreloadFile } from '../file.js';
+import { Stats } from '../stats.js';
+import LockedFS from './Locked.js';
+import { dirname } from '../emulation/path.js';
+import { Cred } from '../cred.js';
+import { decode, encode } from '../utils.js';
+/**
+ * @internal
+ */
+const deletionLogPath = '/.deleted';
+/**
+ * Overlays a RO file to make it writable.
+ */
+class OverlayFile extends PreloadFile {
+    constructor(fs, path, flag, stats, data) {
+        super(fs, path, flag, stats, data);
+    }
+    async sync() {
+        if (!this.isDirty()) {
+            return;
+        }
+        await this.fs.sync(this.path, this.buffer, this.stats);
+        this.resetDirty();
+    }
+    syncSync() {
+        if (this.isDirty()) {
+            this.fs.syncSync(this.path, this.buffer, this.stats);
+            this.resetDirty();
+        }
+    }
+    async close() {
+        await this.sync();
+    }
+    closeSync() {
+        this.syncSync();
+    }
+}
+/**
+ * OverlayFS makes a read-only filesystem writable by storing writes on a second, writable file system.
+ * Deletes are persisted via metadata stored on the writable file system.
+ *
+ * This class contains no locking whatsoever. It is wrapped in a LockedFS to prevent races.
+ *
+ * @internal
+ */
+export class UnlockedOverlayFS extends FileSystem {
+    async ready() {
+        await this._readable.ready();
+        await this._writable.ready();
+        await this._ready;
+        return this;
+    }
+    constructor({ writable, readable }) {
+        super();
+        this._isInitialized = false;
+        this._deletedFiles = new Set();
+        this._deleteLog = '';
+        // If 'true', we have scheduled a delete log update.
+        this._deleteLogUpdatePending = false;
+        // If 'true', a delete log update is needed after the scheduled delete log
+        // update finishes.
+        this._deleteLogUpdateNeeded = false;
+        this._writable = writable;
+        this._readable = readable;
+        if (this._writable.metadata.readonly) {
+            throw new ApiError(ErrorCode.EINVAL, 'Writable file system must be writable.');
+        }
+        this._ready = this._initialize();
+    }
+    get metadata() {
+        return {
+            ...super.metadata,
+            name: OverlayFS.name,
+            synchronous: this._readable.metadata.synchronous && this._writable.metadata.synchronous,
+            supportsProperties: this._readable.metadata.supportsProperties && this._writable.metadata.supportsProperties,
+        };
+    }
+    getOverlayedFileSystems() {
+        return {
+            readable: this._readable,
+            writable: this._writable,
+        };
+    }
+    async sync(path, data, stats) {
+        const cred = stats.getCred(0, 0);
+        await this.createParentDirectories(path, cred);
+        await this._writable.sync(path, data, stats);
+    }
+    syncSync(path, data, stats) {
+        const cred = stats.getCred(0, 0);
+        this.createParentDirectoriesSync(path, cred);
+        this._writable.syncSync(path, data, stats);
+    }
+    /**
+     * Called once to load up metadata stored on the writable file system.
+     * @internal
+     */
+    async _initialize() {
+        if (this._isInitialized) {
+            return;
+        }
+        // Read deletion log, process into metadata.
+        try {
+            const file = await this._writable.openFile(deletionLogPath, FileFlag.FromString('r'), Cred.Root);
+            const { size } = await file.stat();
+            const { buffer } = await file.read(new Uint8Array(size));
+            this._deleteLog = decode(buffer);
+        }
+        catch (err) {
+            if (err.errno !== ErrorCode.ENOENT) {
+                throw err;
+            }
+        }
+        this._isInitialized = true;
+        this._reparseDeletionLog();
+    }
+    getDeletionLog() {
+        return this._deleteLog;
+    }
+    restoreDeletionLog(log, cred) {
+        this._deleteLog = log;
+        this._reparseDeletionLog();
+        this.updateLog('', cred);
+    }
+    async rename(oldPath, newPath, cred) {
+        this.checkInitialized();
+        this.checkPath(oldPath);
+        this.checkPath(newPath);
+        try {
+            await this._writable.rename(oldPath, newPath, cred);
+        }
+        catch (e) {
+            if (this._deletedFiles.has(oldPath)) {
+                throw ApiError.ENOENT(oldPath);
+            }
+        }
+    }
+    renameSync(oldPath, newPath, cred) {
+        this.checkInitialized();
+        this.checkPath(oldPath);
+        this.checkPath(newPath);
+        try {
+            this._writable.renameSync(oldPath, newPath, cred);
+        }
+        catch (e) {
+            if (this._deletedFiles.has(oldPath)) {
+                throw ApiError.ENOENT(oldPath);
+            }
+        }
+    }
+    async stat(p, cred) {
+        this.checkInitialized();
+        try {
+            return this._writable.stat(p, cred);
+        }
+        catch (e) {
+            if (this._deletedFiles.has(p)) {
+                throw ApiError.ENOENT(p);
+            }
+            const oldStat = Stats.clone(await this._readable.stat(p, cred));
+            // Make the oldStat's mode writable. Preserve the topmost part of the
+            // mode, which specifies if it is a file or a directory.
+            oldStat.mode |= 0o222;
+            return oldStat;
+        }
+    }
+    statSync(p, cred) {
+        this.checkInitialized();
+        try {
+            return this._writable.statSync(p, cred);
+        }
+        catch (e) {
+            if (this._deletedFiles.has(p)) {
+                throw ApiError.ENOENT(p);
+            }
+            const oldStat = Stats.clone(this._readable.statSync(p, cred));
+            // Make the oldStat's mode writable. Preserve the topmost part of the
+            // mode, which specifies if it is a file or a directory.
+            oldStat.mode |= 0o222;
+            return oldStat;
+        }
+    }
+    async openFile(path, flag, cred) {
+        if (await this._writable.exists(path, cred)) {
+            return this._writable.openFile(path, flag, cred);
+        }
+        // Create an OverlayFile.
+        const file = await this._readable.openFile(path, FileFlag.FromString('r'), cred);
+        const stats = Stats.clone(await file.stat());
+        const { buffer } = await file.read(new Uint8Array(stats.size));
+        return new OverlayFile(this, path, flag, stats, buffer);
+    }
+    openFileSync(path, flag, cred) {
+        if (this._writable.existsSync(path, cred)) {
+            return this._writable.openFileSync(path, flag, cred);
+        }
+        // Create an OverlayFile.
+        const file = this._readable.openFileSync(path, FileFlag.FromString('r'), cred);
+        const stats = Stats.clone(file.statSync());
+        const data = new Uint8Array(stats.size);
+        file.readSync(data);
+        return new OverlayFile(this, path, flag, stats, data);
+    }
+    async createFile(path, flag, mode, cred) {
+        this.checkInitialized();
+        await this._writable.createFile(path, flag, mode, cred);
+        return this.openFile(path, flag, cred);
+    }
+    createFileSync(path, flag, mode, cred) {
+        this.checkInitialized();
+        this._writable.createFileSync(path, flag, mode, cred);
+        return this.openFileSync(path, flag, cred);
+    }
+    async link(srcpath, dstpath, cred) {
+        this.checkInitialized();
+        await this._writable.link(srcpath, dstpath, cred);
+    }
+    linkSync(srcpath, dstpath, cred) {
+        this.checkInitialized();
+        this._writable.linkSync(srcpath, dstpath, cred);
+    }
+    async unlink(p, cred) {
+        this.checkInitialized();
+        this.checkPath(p);
+        if (!(await this.exists(p, cred))) {
+            throw ApiError.ENOENT(p);
+        }
+        if (await this._writable.exists(p, cred)) {
+            await this._writable.unlink(p, cred);
+        }
+        // if it still exists add to the delete log
+        if (await this.exists(p, cred)) {
+            this.deletePath(p, cred);
+        }
+    }
+    unlinkSync(p, cred) {
+        this.checkInitialized();
+        this.checkPath(p);
+        if (!this.existsSync(p, cred)) {
+            throw ApiError.ENOENT(p);
+        }
+        if (this._writable.existsSync(p, cred)) {
+            this._writable.unlinkSync(p, cred);
+        }
+        // if it still exists add to the delete log
+        if (this.existsSync(p, cred)) {
+            this.deletePath(p, cred);
+        }
+    }
+    async rmdir(p, cred) {
+        this.checkInitialized();
+        if (!(await this.exists(p, cred))) {
+            throw ApiError.ENOENT(p);
+        }
+        if (await this._writable.exists(p, cred)) {
+            await this._writable.rmdir(p, cred);
+        }
+        if (await this.exists(p, cred)) {
+            // Check if directory is empty.
+            if ((await this.readdir(p, cred)).length > 0) {
+                throw ApiError.ENOTEMPTY(p);
+            }
+            else {
+                this.deletePath(p, cred);
+            }
+        }
+    }
+    rmdirSync(p, cred) {
+        this.checkInitialized();
+        if (!this.existsSync(p, cred)) {
+            throw ApiError.ENOENT(p);
+        }
+        if (this._writable.existsSync(p, cred)) {
+            this._writable.rmdirSync(p, cred);
+        }
+        if (this.existsSync(p, cred)) {
+            // Check if directory is empty.
+            if (this.readdirSync(p, cred).length > 0) {
+                throw ApiError.ENOTEMPTY(p);
+            }
+            else {
+                this.deletePath(p, cred);
+            }
+        }
+    }
+    async mkdir(p, mode, cred) {
+        this.checkInitialized();
+        if (await this.exists(p, cred)) {
+            throw ApiError.EEXIST(p);
+        }
+        // The below will throw should any of the parent directories fail to exist on _writable.
+        await this.createParentDirectories(p, cred);
+        await this._writable.mkdir(p, mode, cred);
+    }
+    mkdirSync(p, mode, cred) {
+        this.checkInitialized();
+        if (this.existsSync(p, cred)) {
+            throw ApiError.EEXIST(p);
+        }
+        // The below will throw should any of the parent directories fail to exist on _writable.
+        this.createParentDirectoriesSync(p, cred);
+        this._writable.mkdirSync(p, mode, cred);
+    }
+    async readdir(p, cred) {
+        this.checkInitialized();
+        const dirStats = await this.stat(p, cred);
+        if (!dirStats.isDirectory()) {
+            throw ApiError.ENOTDIR(p);
+        }
+        // Readdir in both, check delete log on RO file system's listing, merge, return.
+        const contents = [];
+        try {
+            contents.push(...(await this._writable.readdir(p, cred)));
+        }
+        catch (e) {
+            // NOP.
+        }
+        try {
+            contents.push(...(await this._readable.readdir(p, cred)).filter((fPath) => !this._deletedFiles.has(`${p}/${fPath}`)));
+        }
+        catch (e) {
+            // NOP.
+        }
+        const seenMap = {};
+        return contents.filter((fileP) => {
+            const result = !seenMap[fileP];
+            seenMap[fileP] = true;
+            return result;
+        });
+    }
+    readdirSync(p, cred) {
+        this.checkInitialized();
+        const dirStats = this.statSync(p, cred);
+        if (!dirStats.isDirectory()) {
+            throw ApiError.ENOTDIR(p);
+        }
+        // Readdir in both, check delete log on RO file system's listing, merge, return.
+        let contents = [];
+        try {
+            contents = contents.concat(this._writable.readdirSync(p, cred));
+        }
+        catch (e) {
+            // NOP.
+        }
+        try {
+            contents = contents.concat(this._readable.readdirSync(p, cred).filter((fPath) => !this._deletedFiles.has(`${p}/${fPath}`)));
+        }
+        catch (e) {
+            // NOP.
+        }
+        const seenMap = {};
+        return contents.filter((fileP) => {
+            const result = !seenMap[fileP];
+            seenMap[fileP] = true;
+            return result;
+        });
+    }
+    deletePath(p, cred) {
+        this._deletedFiles.add(p);
+        this.updateLog(`d${p}\n`, cred);
+    }
+    async updateLog(addition, cred) {
+        this._deleteLog += addition;
+        if (this._deleteLogUpdatePending) {
+            this._deleteLogUpdateNeeded = true;
+            return;
+        }
+        this._deleteLogUpdatePending = true;
+        const log = await this._writable.openFile(deletionLogPath, FileFlag.FromString('w'), cred);
+        try {
+            await log.write(encode(this._deleteLog));
+            if (this._deleteLogUpdateNeeded) {
+                this._deleteLogUpdateNeeded = false;
+                this.updateLog('', cred);
+            }
+        }
+        catch (e) {
+            this._deleteLogError = e;
+        }
+        finally {
+            this._deleteLogUpdatePending = false;
+        }
+    }
+    _reparseDeletionLog() {
+        this._deletedFiles.clear();
+        for (const entry of this._deleteLog.split('\n')) {
+            if (!entry.startsWith('d')) {
+                continue;
+            }
+            // If the log entry begins w/ 'd', it's a deletion.
+            this._deletedFiles.add(entry.slice(1));
+        }
+    }
+    checkInitialized() {
+        if (!this._isInitialized) {
+            throw new ApiError(ErrorCode.EPERM, 'OverlayFS is not initialized. Please initialize OverlayFS using its initialize() method before using it.');
+        }
+        if (!this._deleteLogError) {
+            return;
+        }
+        const error = this._deleteLogError;
+        this._deleteLogError = null;
+        throw error;
+    }
+    checkPath(path) {
+        if (path == deletionLogPath) {
+            throw ApiError.EPERM(path);
+        }
+    }
+    /**
+     * With the given path, create the needed parent directories on the writable storage
+     * should they not exist. Use modes from the read-only storage.
+     */
+    createParentDirectoriesSync(p, cred) {
+        let parent = dirname(p), toCreate = [];
+        while (!this._writable.existsSync(parent, cred)) {
+            toCreate.push(parent);
+            parent = dirname(parent);
+        }
+        toCreate = toCreate.reverse();
+        for (const p of toCreate) {
+            this._writable.mkdirSync(p, this.statSync(p, cred).mode, cred);
+        }
+    }
+    async createParentDirectories(p, cred) {
+        let parent = dirname(p), toCreate = [];
+        while (!(await this._writable.exists(parent, cred))) {
+            toCreate.push(parent);
+            parent = dirname(parent);
+        }
+        toCreate = toCreate.reverse();
+        for (const p of toCreate) {
+            const stats = await this.stat(p, cred);
+            await this._writable.mkdir(p, stats.mode, cred);
+        }
+    }
+    /**
+     * Helper function:
+     * - Ensures p is on writable before proceeding. Throws an error if it doesn't exist.
+     * - Calls f to perform operation on writable.
+     */
+    operateOnWritable(p, cred) {
+        if (!this.existsSync(p, cred)) {
+            throw ApiError.ENOENT(p);
+        }
+        if (!this._writable.existsSync(p, cred)) {
+            // File is on readable storage. Copy to writable storage before
+            // changing its mode.
+            this.copyToWritableSync(p, cred);
+        }
+    }
+    async operateOnWritableAsync(p, cred) {
+        if (!(await this.exists(p, cred))) {
+            throw ApiError.ENOENT(p);
+        }
+        if (!(await this._writable.exists(p, cred))) {
+            return this.copyToWritable(p, cred);
+        }
+    }
+    /**
+     * Copy from readable to writable storage.
+     * PRECONDITION: File does not exist on writable storage.
+     */
+    copyToWritableSync(p, cred) {
+        const stats = this.statSync(p, cred);
+        if (stats.isDirectory()) {
+            this._writable.mkdirSync(p, stats.mode, cred);
+            return;
+        }
+        const data = new Uint8Array(stats.size);
+        const readable = this._readable.openFileSync(p, FileFlag.FromString('r'), cred);
+        readable.readSync(data);
+        readable.closeSync();
+        const writable = this._writable.openFileSync(p, FileFlag.FromString('w'), cred);
+        writable.writeSync(data);
+        writable.closeSync();
+    }
+    async copyToWritable(p, cred) {
+        const stats = await this.stat(p, cred);
+        if (stats.isDirectory()) {
+            await this._writable.mkdir(p, stats.mode, cred);
+            return;
+        }
+        const data = new Uint8Array(stats.size);
+        const readable = await this._readable.openFile(p, FileFlag.FromString('r'), cred);
+        await readable.read(data);
+        await readable.close();
+        const writable = await this._writable.openFile(p, FileFlag.FromString('w'), cred);
+        await writable.write(data);
+        await writable.close();
+    }
+}
+/**
+ * OverlayFS makes a read-only filesystem writable by storing writes on a second,
+ * writable file system. Deletes are persisted via metadata stored on the writable
+ * file system.
+ */
+export class OverlayFS extends LockedFS {
+    async ready() {
+        await super.ready();
+        return this;
+    }
+    /**
+     * @param options The options to initialize the OverlayFS with
+     */
+    constructor(options) {
+        super(new UnlockedOverlayFS(options));
+    }
+    getOverlayedFileSystems() {
+        return super.fs.getOverlayedFileSystems();
+    }
+    getDeletionLog() {
+        return super.fs.getDeletionLog();
+    }
+    resDeletionLog() {
+        return super.fs.getDeletionLog();
+    }
+    unwrap() {
+        return super.fs;
+    }
+}
+export const Overlay = {
+    name: 'Overlay',
+    options: {
+        writable: {
+            type: 'object',
+            required: true,
+            description: 'The file system to write modified files to.',
+        },
+        readable: {
+            type: 'object',
+            required: true,
+            description: 'The file system that initially populates this file system.',
+        },
+    },
+    isAvailable() {
+        return true;
+    },
+    create(options) {
+        return new OverlayFS(options);
+    },
+};

package/dist/backends/SyncStore.js

@@ -114,12 +114,8 @@ export class SyncStoreFileSystem extends SyncFileSystem {
     }
     get metadata() {
         return {
+            ...super.metadata,
             name: this.store.name,
-            readonly: false,
-            supportsProperties: true,
-            synchronous: true,
-            freeSpace: 0,
-            totalSpace: 0,
         };
     }
     /**

package/dist/backends/backend.d.ts

@@ -9,8 +9,7 @@ export interface OptionConfig<T> {
      */
     type: OptionType | OptionType[];
     /**
-     * Whether or not the option is required (optional can be set to null or undefined).
-     * Defaults to false.
+     * Whether or not the option is required (optional can be set to null or undefined). Defaults to false.
      */
     required?: boolean;
     /**

package/dist/backends/backend.js

@@ -80,5 +80,8 @@ export async function resolveBackendConfig(options) {
     if (!backend) {
         throw new ApiError(ErrorCode.EPERM, `Backend "${backend}" is not available`);
     }
-    return backend.create(options);
+    checkOptions(backend, options);
+    const fs = backend.create(options);
+    await fs.ready();
+    return fs;
 }

package/dist/backends/index.d.ts

@@ -1,6 +1,6 @@
 import { AsyncMirror } from './AsyncMirror.js';
 import { InMemory } from './InMemory.js';
-import { Overlay } from './OverlayFS.js';
+import { Overlay } from './Overlay.js';
 import { Backend } from './backend.js';
 export declare const backends: {
     [backend: string]: Backend;

package/dist/backends/index.js

@@ -1,6 +1,6 @@
 import { AsyncMirror } from './AsyncMirror.js';
 import { InMemory } from './InMemory.js';
-import { Overlay } from './OverlayFS.js';
+import { Overlay } from './Overlay.js';
 export const backends = {};
 export default backends;
 export { AsyncMirror, InMemory, Overlay };