@zenfs/core 0.9.2 → 0.9.4

package/src/backends/backend.ts

@@ -0,0 +1,152 @@
+import type { RequiredKeys } from 'utilium';
+import { ApiError, ErrorCode } from '../ApiError.js';
+import { FileSystem } from '../filesystem.js';
+import { levenshtein } from '../utils.js';
+
+type OptionType = 'string' | 'number' | 'bigint' | 'boolean' | 'symbol' | 'undefined' | 'object' | 'function';
+
+/**
+ * Resolves the type of Backend.options from the options interface
+ */
+type OptionsConfig<T> = {
+	[K in keyof T]: {
+		/**
+		 * The basic JavaScript type(s) for this option.
+		 */
+		type: OptionType | readonly OptionType[];
+
+		/**
+		 * Description of the option. Used in error messages and documentation.
+		 */
+		description: string;
+
+		/**
+		 * Whether or not the option is required (optional can be set to null or undefined). Defaults to false.
+		 */
+		required: K extends RequiredKeys<T> ? true : false;
+
+		/**
+		 * A custom validation function to check if the option is valid.
+		 * When async, resolves if valid and rejects if not.
+		 * When sync, it will throw an error if not valid.
+		 */
+		validator?(opt: T[K]): void | Promise<void>;
+	};
+};
+
+/**
+ * A backend
+ */
+export interface Backend<FS extends FileSystem = FileSystem, TOptions extends object = object> {
+	/**
+	 * Create a new instance of the backend
+	 */
+	create(options: TOptions): FS;
+
+	/**
+	 * A name to identify the backend.
+	 */
+	name: string;
+
+	/**
+	 * Describes all of the options available for this backend.
+	 */
+	options: OptionsConfig<TOptions>;
+
+	/**
+	 * Whether the backend is available in the current environment.
+	 * It supports checking synchronously and asynchronously
+	 * Sync:
+	 * Returns 'true' if this backend is available in the current
+	 * environment. For example, a `localStorage`-backed filesystem will return
+	 * 'false' if the browser does not support that API.
+	 *
+	 * Defaults to 'false', as the FileSystem base class isn't usable alone.
+	 */
+	isAvailable(): boolean | Promise<boolean>;
+}
+
+/**
+ * @internal
+ */
+export function isBackend(arg: unknown): arg is Backend {
+	return arg != null && typeof arg == 'object' && 'isAvailable' in arg && typeof arg.isAvailable == 'function' && 'create' in arg && typeof arg.create == 'function';
+}
+
+/**
+ * Checks that the given options object is valid for the file system options.
+ * @internal
+ */
+export async function checkOptions<T extends Backend>(backend: T, opts: object): Promise<void> {
+	if (typeof opts != 'object' || opts === null) {
+		throw new ApiError(ErrorCode.EINVAL, 'Invalid options');
+	}
+
+	// Check for required options.
+	for (const [optName, opt] of Object.entries(backend.options)) {
+		const providedValue = opts?.[optName];
+
+		if (providedValue === undefined || providedValue === null) {
+			if (!opt.required) {
+				continue;
+			}
+			/* Required option not provided.
+			if any incorrect options provided, which ones are close to the provided one?
+			(edit distance 5 === close)*/
+			const incorrectOptions = Object.keys(opts)
+				.filter(o => !(o in backend.options))
+				.map((a: string) => {
+					return { str: a, distance: levenshtein(optName, a) };
+				})
+				.filter(o => o.distance < 5)
+				.sort((a, b) => a.distance - b.distance);
+
+			throw new ApiError(
+				ErrorCode.EINVAL,
+				`${backend.name}: Required option '${optName}' not provided.${
+					incorrectOptions.length > 0 ? ` You provided '${incorrectOptions[0].str}', did you mean '${optName}'.` : ''
+				}`
+			);
+		}
+		// Option provided, check type.
+		const typeMatches = Array.isArray(opt.type) ? opt.type.indexOf(typeof providedValue) != -1 : typeof providedValue == opt.type;
+		if (!typeMatches) {
+			throw new ApiError(
+				ErrorCode.EINVAL,
+				`${backend.name}: Value provided for option ${optName} is not the proper type. Expected ${
+					Array.isArray(opt.type) ? `one of {${opt.type.join(', ')}}` : opt.type
+				}, but received ${typeof providedValue}`
+			);
+		}
+
+		if (opt.validator) {
+			await opt.validator(providedValue);
+		}
+		// Otherwise: All good!
+	}
+}
+
+export function createBackend<B extends Backend>(backend: B, options?: object): Promise<ReturnType<B['create']>> {
+	checkOptions(backend, options);
+	const fs = <ReturnType<B['create']>>backend.create(options);
+	return fs.ready();
+}
+
+/**
+ * Specifies a file system backend type and its options.
+ *
+ * Individual options can recursively contain BackendConfig objects for
+ * option values that require file systems.
+ *
+ * The option object for each file system corresponds to that file system's option object passed to its `Create()` method.
+ */
+export type BackendConfiguration<FS extends FileSystem = FileSystem, TOptions extends object = object> = TOptions & {
+	backend: Backend<FS, TOptions>;
+};
+
+/**
+ * @internal
+ */
+export function isBackendConfig(arg: unknown): arg is BackendConfiguration {
+	return arg != null && typeof arg == 'object' && 'backend' in arg && isBackend(arg.backend);
+}

package/src/config.ts

@@ -0,0 +1,101 @@
+import { ApiError, ErrorCode } from './ApiError.js';
+import type { Backend, BackendConfiguration } from './backends/backend.js';
+import { checkOptions, isBackend, isBackendConfig } from './backends/backend.js';
+import * as fs from './emulation/index.js';
+import { setCred, type MountMapping } from './emulation/shared.js';
+import { FileSystem } from './filesystem.js';
+
+/**
+ * Configuration for a specific mount point
+ */
+export type MountConfiguration<FS extends FileSystem = FileSystem, TOptions extends object = object> = FS | BackendConfiguration<FS, TOptions> | Backend<FS, TOptions>;
+
+function isMountConfig(arg: unknown): arg is MountConfiguration {
+	return isBackendConfig(arg) || isBackend(arg) || arg instanceof FileSystem;
+}
+
+/**
+ * Retrieve a file system with the given configuration.
+ * @param config A BackendConfig object.
+ */
+export async function resolveMountConfig<FS extends FileSystem, TOptions extends object = object>(config: MountConfiguration<FS, TOptions>, _depth = 0): Promise<FS> {
+	if (typeof config !== 'object' || config == null) {
+		throw new ApiError(ErrorCode.EINVAL, 'Invalid options on mount configuration');
+	}
+
+	if (!isMountConfig(config)) {
+		throw new ApiError(ErrorCode.EINVAL, 'Invalid mount configuration');
+	}
+
+	if (config instanceof FileSystem) {
+		return config;
+	}
+
+	if (isBackend(config)) {
+		config = <BackendConfiguration<FS, TOptions>>{ backend: config };
+	}
+
+	for (const [key, value] of Object.entries(config)) {
+		if (key == 'backend') {
+			continue;
+		}
+
+		if (!isMountConfig(value)) {
+			continue;
+		}
+
+		if (_depth > 10) {
+			throw new ApiError(ErrorCode.EINVAL, 'Invalid configuration, too deep and possibly infinite');
+		}
+
+		config[key] = await resolveMountConfig(value, ++_depth);
+	}
+
+	const { backend } = config;
+
+	if (!(await backend.isAvailable())) {
+		throw new ApiError(ErrorCode.EPERM, 'Backend not available: ' + backend);
+	}
+	checkOptions(backend, config);
+	const mount = backend.create(config);
+	await mount.ready();
+	return mount;
+}
+
+/**
+ *A mapping of mount points to their configurations
+ */
+export type MappingConfiguration = Partial<{
+	uid: number;
+	gid: number;
+}> &
+	Record<string, FileSystem | BackendConfiguration | Backend>;
+
+/**
+ * Configuration for the file systems
+ */
+export type Configuration = MountConfiguration | MappingConfiguration;
+
+/**
+ * Creates filesystems with the given configuration, and initializes ZenFS with it.
+ * @see Configuration for more info on the configuration object.
+ */
+export async function configure(config: Configuration): Promise<void> {
+	const uid = 'uid' in config ? +config.uid || 0 : 0;
+	const gid = 'gid' in config ? +config.gid || 0 : 0;
+
+	if (isMountConfig(config)) {
+		// single FS
+		config = { '/': config };
+	}
+
+	for (const [point, value] of Object.entries(config)) {
+		if (point == 'uid' || point == 'gid' || typeof value == 'number') {
+			continue;
+		}
+		config[point] = await resolveMountConfig(value);
+	}
+
+	fs.mountMapping(<MountMapping>config);
+	setCred({ uid, gid, suid: uid, sgid: gid, euid: uid, egid: gid });
+}

package/src/cred.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 Cred {
+	uid: number;
+	gid: number;
+	suid: number;
+	sgid: number;
+	euid: number;
+	egid: number;
+}
+
+export const rootCred: Cred = {
+	uid: 0,
+	gid: 0,
+	suid: 0,
+	sgid: 0,
+	euid: 0,
+	egid: 0,
+};