@zenfs/core 0.9.2 → 0.9.4

package/src/inode.ts

@@ -0,0 +1,229 @@
+import { Stats, type StatsLike } from './stats.js';
+
+/**
+ * Alias for an ino.
+ * This will be helpful if in the future inode numbers/IDs are changed to strings or numbers.
+ */
+export type Ino = bigint;
+
+/**
+ * Max 32-bit integer
+ * @hidden
+ */
+export const size_max = 2 ** 32 - 1;
+
+/**
+ * Room inode
+ * @hidden
+ */
+export const rootIno: Ino = 0n;
+
+/**
+ * Generates a random 32 bit integer, then converts to a hex string
+ */
+function _random() {
+	return Math.round(Math.random() * 2 ** 32).toString(16);
+}
+
+/**
+ * Generate a random ino
+ * @internal
+ */
+export function randomIno(): Ino {
+	return BigInt('0x' + _random() + _random());
+}
+
+/**
+ * Offsets for inode members
+ */
+enum Offset {
+	ino = 0,
+	size = 8, // offsets with a 64-bit size
+	mode = 12, // 16
+	nlink = 14, // 18
+	uid = 18, // 22
+	gid = 22, // 26
+	atime = 26, // 30
+	birthtime = 34, // 38
+	mtime = 42, // 46
+	ctime = 50, // 54
+	end = 58, // 62
+}
+
+/**
+ * Generic inode definition that can easily be serialized.
+ */
+export class Inode implements StatsLike {
+	public readonly buffer: ArrayBufferLike;
+
+	public get data(): Uint8Array {
+		return new Uint8Array(this.buffer);
+	}
+
+	protected view: DataView;
+
+	constructor(buffer?: ArrayBufferLike) {
+		const setDefaults = !buffer;
+		buffer ??= new ArrayBuffer(Offset.end);
+		if (buffer?.byteLength < Offset.end) {
+			throw new RangeError(`Can not create an inode from a buffer less than ${Offset.end} bytes`);
+		}
+		this.view = new DataView(buffer);
+		this.buffer = buffer;
+
+		if (!setDefaults) {
+			return;
+		}
+
+		// set defaults on a fresh inode
+		this.ino = randomIno();
+		this.nlink = 1;
+		this.size = 4096;
+		const now = Date.now();
+		this.atimeMs = now;
+		this.mtimeMs = now;
+		this.ctimeMs = now;
+		this.birthtimeMs = now;
+	}
+
+	public get ino(): Ino {
+		return this.view.getBigUint64(Offset.ino, true);
+	}
+
+	public set ino(value: Ino) {
+		this.view.setBigUint64(Offset.ino, value, true);
+	}
+
+	public get size(): number {
+		return this.view.getUint32(Offset.size, true);
+	}
+
+	public set size(value: number) {
+		this.view.setUint32(Offset.size, value, true);
+	}
+
+	public get mode(): number {
+		return this.view.getUint16(Offset.mode, true);
+	}
+
+	public set mode(value: number) {
+		this.view.setUint16(Offset.mode, value, true);
+	}
+
+	public get nlink(): number {
+		return this.view.getUint32(Offset.nlink, true);
+	}
+
+	public set nlink(value: number) {
+		this.view.setUint32(Offset.nlink, value, true);
+	}
+
+	public get uid(): number {
+		return this.view.getUint32(Offset.uid, true);
+	}
+
+	public set uid(value: number) {
+		this.view.setUint32(Offset.uid, value, true);
+	}
+
+	public get gid(): number {
+		return this.view.getUint32(Offset.gid, true);
+	}
+
+	public set gid(value: number) {
+		this.view.setUint32(Offset.gid, value, true);
+	}
+
+	public get atimeMs(): number {
+		return this.view.getFloat64(Offset.atime, true);
+	}
+
+	public set atimeMs(value: number) {
+		this.view.setFloat64(Offset.atime, value, true);
+	}
+
+	public get birthtimeMs(): number {
+		return this.view.getFloat64(Offset.birthtime, true);
+	}
+
+	public set birthtimeMs(value: number) {
+		this.view.setFloat64(Offset.birthtime, value, true);
+	}
+
+	public get mtimeMs(): number {
+		return this.view.getFloat64(Offset.mtime, true);
+	}
+
+	public set mtimeMs(value: number) {
+		this.view.setFloat64(Offset.mtime, value, true);
+	}
+
+	public get ctimeMs(): number {
+		return this.view.getFloat64(Offset.ctime, true);
+	}
+
+	public set ctimeMs(value: number) {
+		this.view.setFloat64(Offset.ctime, value, true);
+	}
+
+	/**
+	 * Handy function that converts the Inode to a Node Stats object.
+	 */
+	public toStats(): Stats {
+		return new Stats(this);
+	}
+
+	/**
+	 * 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.
+	 */
+	public update(stats: Readonly<Stats>): boolean {
+		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;
+		}
+
+		if (this.nlink !== stats.nlink) {
+			this.nlink = stats.nlink;
+			hasChanged = true;
+		}
+
+		if (this.uid !== stats.uid) {
+			this.uid = stats.uid;
+			hasChanged = true;
+		}
+
+		if (this.uid !== stats.uid) {
+			this.uid = stats.uid;
+			hasChanged = true;
+		}
+
+		if (this.atimeMs !== stats.atimeMs) {
+			this.atimeMs = stats.atimeMs;
+			hasChanged = true;
+		}
+		if (this.mtimeMs !== stats.mtimeMs) {
+			this.mtimeMs = stats.mtimeMs;
+			hasChanged = true;
+		}
+
+		if (this.ctimeMs !== stats.ctimeMs) {
+			this.ctimeMs = stats.ctimeMs;
+			hasChanged = true;
+		}
+
+		return hasChanged;
+	}
+}

package/src/mutex.ts

@@ -0,0 +1,52 @@
+/**
+ * Non-recursive mutex
+ * @internal
+ */
+export class Mutex {
+	private _locks: Map<string, (() => void)[]> = new Map();
+
+	public lock(path: string): Promise<void> {
+		return new Promise(resolve => {
+			if (this._locks.has(path)) {
+				this._locks.get(path).push(resolve);
+			} else {
+				this._locks.set(path, []);
+			}
+		});
+	}
+
+	public unlock(path: string): void {
+		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);
+	}
+
+	public tryLock(path: string): boolean {
+		if (this._locks.has(path)) {
+			return false;
+		}
+
+		this._locks.set(path, []);
+		return true;
+	}
+
+	public isLocked(path: string): boolean {
+		return this._locks.has(path);
+	}
+}

package/src/stats.ts

@@ -0,0 +1,385 @@
+import type * as Node from 'fs';
+import { Cred } from './cred.js';
+import { S_IFDIR, S_IFLNK, S_IFMT, S_IFREG, S_IRWXG, S_IRWXO, S_IRWXU } from './emulation/constants.js';
+
+/**
+ * Indicates the type of the given file. Applied to 'mode'.
+ */
+export enum FileType {
+	FILE = S_IFREG,
+	DIRECTORY = S_IFDIR,
+	SYMLINK = S_IFLNK,
+}
+
+/**
+ *
+ */
+export interface StatsLike {
+	/**
+	 * Size of the item in bytes.
+	 * For directories/symlinks, this is normally the size of the struct that represents the item.
+	 */
+	size: number | bigint;
+	/**
+	 * Unix-style file mode (e.g. 0o644) that includes the item type
+	 * Type of the item can be FILE, DIRECTORY, SYMLINK, or SOCKET
+	 */
+	mode: number | bigint;
+	/**
+	 * time of last access, in milliseconds since epoch
+	 */
+	atimeMs: number | bigint;
+	/**
+	 * time of last modification, in milliseconds since epoch
+	 */
+	mtimeMs: number | bigint;
+	/**
+	 * time of last time file status was changed, in milliseconds since epoch
+	 */
+	ctimeMs: number | bigint;
+	/**
+	 * time of file creation, in milliseconds since epoch
+	 */
+	birthtimeMs: number | bigint;
+	/**
+	 * the id of the user that owns the file
+	 */
+	uid: number | bigint;
+	/**
+	 * the id of the group that owns the file
+	 */
+	gid: number | bigint;
+}
+
+/**
+ * Provides information about a particular entry in the file system.
+ * Common code used by both Stats and BigIntStats.
+ */
+export abstract class StatsCommon<T extends number | bigint> implements Node.StatsBase<T>, StatsLike {
+	protected abstract _isBigint: boolean;
+
+	protected get _typename(): string {
+		return this._isBigint ? 'bigint' : 'number';
+	}
+
+	protected get _typename_inverse(): string {
+		return this._isBigint ? 'number' : 'bigint';
+	}
+
+	protected _convert(arg: number | bigint | string | boolean): T {
+		return <T>(this._isBigint ? BigInt(arg) : Number(arg));
+	}
+
+	public blocks: T;
+
+	/**
+	 * Unix-style file mode (e.g. 0o644) that includes the type of the item.
+	 * Type of the item can be FILE, DIRECTORY, SYMLINK, or SOCKET
+	 */
+	public mode: T;
+
+	/**
+	 * ID of device containing file
+	 */
+	public dev: T = this._convert(0);
+
+	/**
+	 * inode number
+	 */
+	public ino: T = this._convert(0);
+
+	/**
+	 * device ID (if special file)
+	 */
+	public rdev: T = this._convert(0);
+
+	/**
+	 * number of hard links
+	 */
+	public nlink: T = this._convert(1);
+
+	/**
+	 * blocksize for file system I/O
+	 */
+	public blksize: T = this._convert(4096);
+
+	/**
+	 * user ID of owner
+	 */
+	public uid: T = this._convert(0);
+
+	/**
+	 * group ID of owner
+	 */
+	public gid: T = this._convert(0);
+
+	/**
+	 * Some file systems stash data on stats objects.
+	 */
+	public fileData?: Uint8Array = null;
+
+	/**
+	 * time of last access, in milliseconds since epoch
+	 */
+	public atimeMs: T;
+
+	public get atime(): Date {
+		return new Date(Number(this.atimeMs));
+	}
+
+	public set atime(value: Date) {
+		this.atimeMs = this._convert(value.getTime());
+	}
+
+	/**
+	 * time of last modification, in milliseconds since epoch
+	 */
+	public mtimeMs: T;
+
+	public get mtime(): Date {
+		return new Date(Number(this.mtimeMs));
+	}
+
+	public set mtime(value: Date) {
+		this.mtimeMs = this._convert(value.getTime());
+	}
+
+	/**
+	 * time of last time file status was changed, in milliseconds since epoch
+	 */
+	public ctimeMs: T;
+
+	public get ctime(): Date {
+		return new Date(Number(this.ctimeMs));
+	}
+
+	public set ctime(value: Date) {
+		this.ctimeMs = this._convert(value.getTime());
+	}
+
+	/**
+	 * time of file creation, in milliseconds since epoch
+	 */
+	public birthtimeMs: T;
+
+	public get birthtime(): Date {
+		return new Date(Number(this.birthtimeMs));
+	}
+
+	public set birthtime(value: Date) {
+		this.birthtimeMs = this._convert(value.getTime());
+	}
+
+	/**
+	 * Size of the item in bytes.
+	 * For directories/symlinks, this is normally the size of the struct that represents the item.
+	 */
+	public size: T;
+
+	/**
+	 * Creates a new stats instance from a stats-like object. Can be used to copy stats (note)
+	 */
+	constructor({ atimeMs, mtimeMs, ctimeMs, birthtimeMs, uid, gid, size, mode }: Partial<StatsLike> = {}) {
+		const currentTime = Date.now();
+		const resolveT = (val: number | bigint, _default: number) => <T>(typeof val == this._typename ? val : this._convert(typeof val == this._typename_inverse ? val : _default));
+		this.atimeMs = resolveT(atimeMs, currentTime);
+		this.mtimeMs = resolveT(mtimeMs, currentTime);
+		this.ctimeMs = resolveT(ctimeMs, currentTime);
+		this.birthtimeMs = resolveT(birthtimeMs, currentTime);
+		this.uid = resolveT(uid, 0);
+		this.gid = resolveT(gid, 0);
+		this.size = this._convert(size);
+		const itemType: FileType = Number(mode) & S_IFMT || FileType.FILE;
+
+		if (mode) {
+			this.mode = this._convert(mode);
+		} else {
+			switch (itemType) {
+				case FileType.FILE:
+					this.mode = this._convert(0o644);
+					break;
+				case FileType.DIRECTORY:
+				default:
+					this.mode = this._convert(0o777);
+			}
+		}
+		// number of 512B blocks allocated
+		this.blocks = this._convert(Math.ceil(Number(size) / 512));
+		// Check if mode also includes top-most bits, which indicate the file's type.
+		if ((this.mode & S_IFMT) == 0) {
+			this.mode = <T>(this.mode | this._convert(itemType));
+		}
+	}
+
+	/**
+	 * @returns true if this item is a file.
+	 */
+	public isFile(): boolean {
+		return (this.mode & S_IFMT) === S_IFREG;
+	}
+
+	/**
+	 * @returns True if this item is a directory.
+	 */
+	public isDirectory(): boolean {
+		return (this.mode & S_IFMT) === S_IFDIR;
+	}
+
+	/**
+	 * @returns true if this item is a symbolic link
+	 */
+	public isSymbolicLink(): boolean {
+		return (this.mode & S_IFMT) === S_IFLNK;
+	}
+
+	// Currently unsupported
+
+	public isSocket(): boolean {
+		return false;
+	}
+
+	public isBlockDevice(): boolean {
+		return false;
+	}
+
+	public isCharacterDevice(): boolean {
+		return false;
+	}
+
+	public isFIFO(): boolean {
+		return false;
+	}
+
+	/**
+	 * Checks if a given user/group has access to this item
+	 * @param mode The requested access, combination of W_OK, R_OK, and X_OK
+	 * @param cred The requesting credentials
+	 * @returns True if the request has access, false if the request does not
+	 * @internal
+	 */
+	public hasAccess(mode: number, cred: Cred): boolean {
+		if (cred.euid === 0 || cred.egid === 0) {
+			//Running as root
+			return true;
+		}
+
+		// Mask for
+		const adjusted = (cred.uid == this.uid ? S_IRWXU : 0) | (cred.gid == this.gid ? S_IRWXG : 0) | S_IRWXO;
+		return (mode & this.mode & adjusted) == mode;
+	}
+
+	/**
+	 * Convert the current stats object into a credentials object
+	 * @internal
+	 */
+	public cred(uid: number = Number(this.uid), gid: number = Number(this.gid)): Cred {
+		return {
+			uid,
+			gid,
+			suid: Number(this.uid),
+			sgid: Number(this.gid),
+			euid: uid,
+			egid: 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.
+	 * @internal
+	 */
+	public chmod(mode: number): void {
+		this.mode = this._convert((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)
+	 * @internal
+	 */
+	public chown(uid: number | bigint, gid: number | bigint): void {
+		uid = Number(uid);
+		gid = Number(gid);
+		if (!isNaN(uid) && 0 <= uid && uid < 2 ** 32) {
+			this.uid = this._convert(uid);
+		}
+		if (!isNaN(gid) && 0 <= gid && gid < 2 ** 32) {
+			this.gid = this._convert(gid);
+		}
+	}
+}
+
+/**
+ * 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 extends StatsCommon<number> implements Node.Stats, StatsLike {
+	protected _isBigint = false;
+
+	/**
+	 * Clones the stats object.
+	 * @deprecated use `new Stats(stats)`
+	 */
+	public static clone(stats: Stats): Stats {
+		return new Stats(stats);
+	}
+}
+Stats satisfies typeof Node.Stats;
+
+/**
+ * Stats with bigint
+ * @todo Implement with bigint instead of wrapping Stats
+ */
+export class BigIntStats extends StatsCommon<bigint> implements Node.BigIntStats, StatsLike {
+	protected _isBigint = true;
+
+	public atimeNs: bigint;
+	public mtimeNs: bigint;
+	public ctimeNs: bigint;
+	public birthtimeNs: bigint;
+
+	/**
+	 * Clone a stats object.
+	 * @deprecated use `new BigIntStats(stats)`
+	 */
+	public static clone(stats: BigIntStats | Stats): BigIntStats {
+		return new BigIntStats(stats);
+	}
+}
+
+export class StatsFs implements Node.StatsFsBase<number> {
+	/** Type of file system. */
+	public type: number;
+	/**  Optimal transfer block size. */
+	public bsize: number;
+	/**  Total data blocks in file system. */
+	public blocks: number;
+	/** Free blocks in file system. */
+	public bfree: number;
+	/** Available blocks for unprivileged users */
+	public bavail: number;
+	/** Total file nodes in file system. */
+	public files: number;
+	/** Free file nodes in file system. */
+	public ffree: number;
+}
+
+export class BigIntStatsFs implements Node.StatsFsBase<bigint> {
+	/** Type of file system. */
+	public type: bigint;
+	/**  Optimal transfer block size. */
+	public bsize: bigint;
+	/**  Total data blocks in file system. */
+	public blocks: bigint;
+	/** Free blocks in file system. */
+	public bfree: bigint;
+	/** Available blocks for unprivileged users */
+	public bavail: bigint;
+	/** Total file nodes in file system. */
+	public files: bigint;
+	/** Free file nodes in file system. */
+	public ffree: bigint;
+}