@zenfs/core 1.1.6 → 1.2.0

package/src/backends/store/simple.ts

@@ -0,0 +1,146 @@
+import type { Ino } from '../../inode.js';
+import { SyncTransaction, type Store } from './store.js';
+
+/**
+ * An interface for simple synchronous stores that don't have special support for transactions and such.
+ */
+export interface SimpleSyncStore extends Store {
+	get(ino: Ino): Uint8Array | undefined;
+	set(ino: Ino, data: Uint8Array): void;
+	delete(ino: Ino): void;
+}
+
+/**
+ * An interface for simple asynchronous stores that don't have special support for transactions and such.
+ * This class adds caching at the store level.
+ */
+export abstract class SimpleAsyncStore implements SimpleSyncStore {
+	public abstract name: string;
+
+	protected cache: Map<Ino, Uint8Array> = new Map();
+
+	protected queue: Set<Promise<unknown>> = new Set();
+
+	protected abstract entries(): Promise<Iterable<[Ino, Uint8Array]>>;
+
+	public get(ino: Ino): Uint8Array | undefined {
+		return this.cache.get(ino);
+	}
+
+	public set(ino: Ino, data: Uint8Array): void {
+		this.cache.set(ino, data);
+		this.queue.add(this._set(ino, data));
+	}
+
+	protected abstract _set(ino: Ino, data: Uint8Array): Promise<void>;
+
+	public delete(ino: Ino): void {
+		this.cache.delete(ino);
+		this.queue.add(this._delete(ino));
+	}
+
+	protected abstract _delete(ino: Ino): Promise<void>;
+
+	public clearSync(): void {
+		this.cache.clear();
+		this.queue.add(this.clear());
+	}
+
+	public abstract clear(): Promise<void>;
+
+	public async sync(): Promise<void> {
+		for (const [ino, data] of await this.entries()) {
+			if (!this.cache.has(ino)) {
+				this.cache.set(ino, data);
+			}
+		}
+		for (const promise of this.queue) {
+			await promise;
+		}
+	}
+
+	public transaction(): SimpleTransaction {
+		return new SimpleTransaction(this);
+	}
+}
+
+/**
+ * Transaction for simple stores.
+ * @see SimpleSyncStore
+ * @see SimpleAsyncStore
+ */
+export class SimpleTransaction extends SyncTransaction<SimpleSyncStore> {
+	/**
+	 * Stores data in the keys we modify prior to modifying them.
+	 * Allows us to roll back commits.
+	 */
+	protected originalData: Map<Ino, Uint8Array | void> = new Map();
+	/**
+	 * List of keys modified in this transaction, if any.
+	 */
+	protected modifiedKeys: Set<Ino> = new Set();
+
+	protected declare store: SimpleSyncStore;
+
+	public getSync(ino: Ino): Uint8Array {
+		const val = this.store.get(ino);
+		this.stashOldValue(ino, val);
+		return val!;
+	}
+
+	public setSync(ino: Ino, data: Uint8Array): void {
+		this.markModified(ino);
+		return this.store.set(ino, data);
+	}
+
+	public removeSync(ino: Ino): void {
+		this.markModified(ino);
+		this.store.delete(ino);
+	}
+
+	public commitSync(): void {
+		this.done = true;
+	}
+
+	public abortSync(): void {
+		if (!this.done) {
+			return;
+		}
+		// Rollback old values.
+		for (const key of this.modifiedKeys) {
+			const value = this.originalData.get(key);
+			if (!value) {
+				// Key didn't exist.
+				this.store.delete(key);
+			} else {
+				// Key existed. Store old value.
+				this.store.set(key, value);
+			}
+		}
+		this.done = true;
+	}
+
+	/**
+	 * Stashes given key value pair into `originalData` if it doesn't already
+	 * exist. Allows us to stash values the program is requesting anyway to
+	 * prevent needless `get` requests if the program modifies the data later
+	 * on during the transaction.
+	 */
+	protected stashOldValue(ino: Ino, value?: Uint8Array): void {
+		// Keep only the earliest value in the transaction.
+		if (!this.originalData.has(ino)) {
+			this.originalData.set(ino, value);
+		}
+	}
+
+	/**
+	 * Marks `ino` as modified, and stashes its value if it has not been
+	 * stashed already.
+	 */
+	protected markModified(ino: Ino): void {
+		this.modifiedKeys.add(ino);
+		if (!this.originalData.has(ino)) {
+			this.originalData.set(ino, this.store.get(ino));
+		}
+	}
+}

package/src/backends/store/store.ts

@@ -0,0 +1,173 @@
+import { ErrnoError } from '../../error.js';
+import type { Ino } from '../../inode.js';
+import '../../polyfills.js';
+
+/**
+ * Represents a key-value store.
+ */
+export interface Store {
+	/**
+	 * The name of the store.
+	 */
+	readonly name: string;
+
+	/**
+	 * Syncs the store
+	 */
+	sync(): Promise<void>;
+
+	/**
+	 * Empties the store completely.
+	 */
+	clear(): Promise<void> | void;
+
+	/**
+	 * Empties the store completely.
+	 */
+	clearSync(): void;
+
+	/**
+	 * Begins a new transaction.
+	 */
+	transaction(): Transaction;
+}
+
+/**
+ * A transaction for a store.
+ */
+export abstract class Transaction<T extends Store = Store> {
+	public constructor(protected store: T) {}
+
+	/**
+	 * Whether the transaction was commited or aborted
+	 */
+	protected done: boolean = false;
+
+	/**
+	 * Retrieves the data at `ino`.
+	 * @param ino The key to look under for data.
+	 */
+	public abstract get(ino: Ino): Promise<Uint8Array>;
+
+	/**
+	 * Retrieves the data at `ino`.
+	 * Throws an error if an error occurs or if the key does not exist.
+	 * @param ino The key to look under for data.
+	 * @return The data stored under the key, or undefined if not present.
+	 */
+	public abstract getSync(ino: Ino): Uint8Array;
+
+	/**
+	 * Adds the data to the store under `ino`. Overwrites any existing data.
+	 * @param ino The key to add the data under.
+	 * @param data The data to add to the store.
+	 */
+	public abstract set(ino: Ino, data: Uint8Array): Promise<void>;
+
+	/**
+	 * Adds the data to the store under `ino`.
+	 * @param ino The key to add the data under.
+	 * @param data The data to add to the store.
+	 */
+	public abstract setSync(ino: Ino, data: Uint8Array): void;
+
+	/**
+	 * Deletes the data at `ino`.
+	 * @param ino The key to delete from the store.
+	 */
+	public abstract remove(ino: Ino): Promise<void>;
+
+	/**
+	 * Deletes the data at `ino`.
+	 * @param ino The key to delete from the store.
+	 */
+	public abstract removeSync(ino: Ino): void;
+
+	/**
+	 * Commits the transaction.
+	 */
+	public abstract commit(): Promise<void>;
+
+	public async [Symbol.asyncDispose]() {
+		if (this.done) {
+			return;
+		}
+
+		await this.abort();
+	}
+
+	/**
+	 * Commits the transaction.
+	 */
+	public abstract commitSync(): void;
+
+	public [Symbol.dispose]() {
+		if (this.done) {
+			return;
+		}
+
+		this.abortSync();
+	}
+
+	/**
+	 * Aborts and rolls back the transaction.
+	 */
+	public abstract abort(): Promise<void>;
+
+	/**
+	 * Aborts and rolls back the transaction.
+	 */
+	public abstract abortSync(): void;
+}
+
+/**
+ * Transaction that implements asynchronous operations with synchronous ones
+ */
+export abstract class SyncTransaction<T extends Store = Store> extends Transaction<T> {
+	/* eslint-disable @typescript-eslint/require-await */
+	public async get(ino: Ino): Promise<Uint8Array> {
+		return this.getSync(ino);
+	}
+
+	public async set(ino: bigint, data: Uint8Array): Promise<void> {
+		return this.setSync(ino, data);
+	}
+
+	public async remove(ino: Ino): Promise<void> {
+		return this.removeSync(ino);
+	}
+
+	public async commit(): Promise<void> {
+		return this.commitSync();
+	}
+
+	public async abort(): Promise<void> {
+		return this.abortSync();
+	}
+	/* eslint-enable @typescript-eslint/require-await */
+}
+
+/**
+ * Transaction that only supports asynchronous operations
+ */
+export abstract class AsyncTransaction<T extends Store = Store> extends Transaction<T> {
+	public getSync(): Uint8Array {
+		throw ErrnoError.With('ENOSYS', undefined, 'AsyncTransaction.getSync');
+	}
+
+	public setSync(): void {
+		throw ErrnoError.With('ENOSYS', undefined, 'AsyncTransaction.setSync');
+	}
+
+	public removeSync(): void {
+		throw ErrnoError.With('ENOSYS', undefined, 'AsyncTransaction.removeSync');
+	}
+
+	public commitSync(): void {
+		throw ErrnoError.With('ENOSYS', undefined, 'AsyncTransaction.commitSync');
+	}
+
+	public abortSync(): void {
+		throw ErrnoError.With('ENOSYS', undefined, 'AsyncTransaction.abortSync');
+	}
+}

package/src/config.ts

@@ -0,0 +1,173 @@
+import type { Backend, BackendConfiguration, FilesystemOf, SharedConfig } from './backends/backend.js';
+import { checkOptions, isBackend, isBackendConfig } from './backends/backend.js';
+import { credentials } from './credentials.js';
+import { DeviceFS, fullDevice, nullDevice, randomDevice, zeroDevice } from './devices.js';
+import * as cache from './emulation/cache.js';
+import * as fs from './emulation/index.js';
+import type { AbsolutePath } from './emulation/path.js';
+import { config, type MountObject } from './emulation/shared.js';
+import { Errno, ErrnoError } from './error.js';
+import { FileSystem } from './filesystem.js';
+
+/**
+ * Configuration for a specific mount point
+ */
+export type MountConfiguration<T extends Backend> = FilesystemOf<T> | BackendConfiguration<T> | T;
+
+function isMountConfig<T extends Backend>(arg: unknown): arg is MountConfiguration<T> {
+	return isBackendConfig(arg) || isBackend(arg) || arg instanceof FileSystem;
+}
+
+/**
+ * Retrieve a file system with `configuration`.
+ * @see MountConfiguration
+ */
+export async function resolveMountConfig<T extends Backend>(configuration: MountConfiguration<T>, _depth = 0): Promise<FilesystemOf<T>> {
+	if (typeof configuration !== 'object' || configuration == null) {
+		throw new ErrnoError(Errno.EINVAL, 'Invalid options on mount configuration');
+	}
+
+	if (!isMountConfig(configuration)) {
+		throw new ErrnoError(Errno.EINVAL, 'Invalid mount configuration');
+	}
+
+	if (configuration instanceof FileSystem) {
+		await configuration.ready();
+		return configuration;
+	}
+
+	if (isBackend(configuration)) {
+		configuration = { backend: configuration } as BackendConfiguration<T>;
+	}
+
+	for (const [key, value] of Object.entries(configuration)) {
+		if (key == 'backend') {
+			continue;
+		}
+
+		if (!isMountConfig(value)) {
+			continue;
+		}
+
+		if (_depth > 10) {
+			throw new ErrnoError(Errno.EINVAL, 'Invalid configuration, too deep and possibly infinite');
+		}
+
+		(configuration as Record<string, FileSystem>)[key] = await resolveMountConfig(value, ++_depth);
+	}
+
+	const { backend } = configuration;
+
+	if (!(await backend.isAvailable())) {
+		throw new ErrnoError(Errno.EPERM, 'Backend not available: ' + backend.name);
+	}
+	await checkOptions(backend, configuration);
+	const mount = (await backend.create(configuration)) as FilesystemOf<T>;
+	mount._disableSync = configuration.disableAsyncCache || false;
+	await mount.ready();
+	return mount;
+}
+
+export interface ConfigMounts {
+	[K: AbsolutePath]: Backend;
+}
+
+/**
+ * Configuration
+ */
+export interface Configuration<T extends ConfigMounts> extends SharedConfig {
+	/**
+	 * An object mapping mount points to mount configuration
+	 */
+	mounts: { [K in keyof T & AbsolutePath]: MountConfiguration<T[K]> };
+
+	/**
+	 * The uid to use
+	 * @default 0
+	 */
+	uid: number;
+
+	/**
+	 * The gid to use
+	 * @default 0
+	 */
+	gid: number;
+
+	/**
+	 * Whether to automatically add normal Linux devices
+	 * @default false
+	 * @experimental
+	 */
+	addDevices: boolean;
+
+	/**
+	 * If true, enables caching stats for certain operations.
+	 * This should reduce the number of stat calls performed.
+	 * @default false
+	 * @experimental
+	 */
+	cacheStats: boolean;
+
+	/**
+	 * If true, disables *all* permissions checking.
+	 * This can increase performance
+	 * @default false
+	 * @experimental
+	 */
+	disableAccessChecks: boolean;
+}
+
+/**
+ * Configures ZenFS with single mount point /
+ */
+export async function configureSingle<T extends Backend>(configuration: MountConfiguration<T>): Promise<void> {
+	if (!isBackendConfig(configuration)) {
+		throw new TypeError('Invalid single mount point configuration');
+	}
+
+	const resolved = await resolveMountConfig(configuration);
+	fs.umount('/');
+	fs.mount('/', resolved);
+}
+
+/**
+ * Configures ZenFS with `configuration`
+ * @see Configuration
+ */
+export async function configure<T extends ConfigMounts>(configuration: Partial<Configuration<T>>): Promise<void> {
+	const uid = 'uid' in configuration ? configuration.uid || 0 : 0;
+	const gid = 'gid' in configuration ? configuration.gid || 0 : 0;
+
+	Object.assign(credentials, { uid, gid, suid: uid, sgid: gid, euid: uid, egid: gid });
+
+	cache.setEnabled(configuration.cacheStats ?? false);
+	config.checkAccess = !configuration.disableAccessChecks;
+
+	if (configuration.addDevices) {
+		const devfs = new DeviceFS();
+		devfs.createDevice('/null', nullDevice);
+		devfs.createDevice('/zero', zeroDevice);
+		devfs.createDevice('/full', fullDevice);
+		devfs.createDevice('/random', randomDevice);
+		await devfs.ready();
+		fs.mount('/dev', devfs);
+	}
+
+	if (!configuration.mounts) {
+		return;
+	}
+
+	for (const [point, mountConfig] of Object.entries(configuration.mounts)) {
+		if (!point.startsWith('/')) {
+			throw new ErrnoError(Errno.EINVAL, 'Mount points must have absolute paths');
+		}
+
+		if (isBackendConfig(mountConfig)) {
+			mountConfig.disableAsyncCache ??= configuration.disableAsyncCache || false;
+		}
+
+		configuration.mounts[point as keyof T & `/${string}`] = await resolveMountConfig(mountConfig);
+	}
+
+	fs.mountObject(configuration.mounts as MountObject);
+}

package/src/credentials.ts

@@ -0,0 +1,31 @@
+/**
+ * Credentials used for various operations.
+ * Similar to Linux's cred struct.
+ * @see https://github.com/torvalds/linux/blob/master/include/linux/cred.h
+ */
+export interface Credentials {
+	uid: number;
+	gid: number;
+	suid: number;
+	sgid: number;
+	euid: number;
+	egid: number;
+}
+
+export const credentials: Credentials = {
+	uid: 0,
+	gid: 0,
+	suid: 0,
+	sgid: 0,
+	euid: 0,
+	egid: 0,
+};
+
+export const rootCredentials: Credentials = {
+	uid: 0,
+	gid: 0,
+	suid: 0,
+	sgid: 0,
+	euid: 0,
+	egid: 0,
+};