@zenfs/core 1.11.4 → 2.0.0

package/dist/vfs/xattr.d.ts

@@ -0,0 +1,116 @@
+import type { BufferEncodingOption, ObjectEncodingOptions } from 'node:fs';
+import type { V_Context } from '../context.js';
+/**
+ * Extended attribute name with namespace prefix.
+ * Format is namespace.attributename where namespace is one of:
+ * - user: User attributes
+ * - trusted: Trusted attributes (privileged)
+ * - system: System attributes
+ * - security: Security attributes
+ *
+ * Note: Currently only the 'user' namespace is supported.
+ */
+export type Name = `${'user' | 'trusted' | 'system' | 'security'}.${string}`;
+/**
+ * Options for xattr operations.
+ */
+export interface Options {
+    /**
+     * If true, don't follow symlinks.
+     * @default false
+     */
+    noFollow?: boolean;
+    /**
+     * Encoding for attribute values.
+     * If 'buffer' or undefined, the value is returned as a Buffer.
+     * Otherwise, the value is returned as a string using the specified encoding.
+     * @default undefined
+     */
+    encoding?: BufferEncoding | 'buffer';
+}
+/**
+ * Options for setting extended attributes.
+ * Extends the base Options with additional flags for create/replace behavior.
+ */
+export interface SetOptions extends Options {
+    /**
+     * If true, fail if the attribute already exists.
+     * @default false
+     */
+    create?: boolean;
+    /**
+     * If true, fail if the attribute does not exist.
+     * @default false
+     */
+    replace?: boolean;
+}
+/**
+ * Gets the value of an extended attribute.
+ *
+ * @param path Path to the file
+ * @param name Name of the attribute to get
+ * @param opt Options for the operation
+ * @returns A buffer containing the attribute value when encoding is 'buffer' or undefined, or a string when a string encoding is specified
+ */
+export declare function get(this: V_Context, path: string, name: Name, opt?: Options & (BufferEncodingOption | {
+    encoding?: null;
+})): Promise<Uint8Array>;
+export declare function get(this: V_Context, path: string, name: Name, opt: Options & ObjectEncodingOptions): Promise<string>;
+/**
+ * Synchronously gets the value of an extended attribute.
+ *
+ * @param path Path to the file
+ * @param name Name of the attribute to get
+ * @param opt Options for the operation
+ * @returns A buffer containing the attribute value when encoding is 'buffer' or undefined, or a string when a string encoding is specified
+ */
+export declare function getSync(this: V_Context, path: string, name: Name, opt?: Options & (BufferEncodingOption | {
+    encoding?: null;
+})): Uint8Array;
+export declare function getSync(this: V_Context, path: string, name: Name, opt: Options & ObjectEncodingOptions): string;
+/**
+ * Sets the value of an extended attribute.
+ *
+ * @param path Path to the file
+ * @param name Name of the attribute to set
+ * @param value Value to set
+ * @param opt Options for the operation
+ */
+export declare function set(this: V_Context, path: string, name: Name, value: string | Uint8Array, opt?: SetOptions): Promise<void>;
+/**
+ * Synchronously sets the value of an extended attribute.
+ *
+ * @param path Path to the file
+ * @param name Name of the attribute to set
+ * @param value Value to set
+ * @param opt Options for the operation
+ */
+export declare function setSync(this: V_Context, path: string, name: Name, value: string | Uint8Array, opt?: SetOptions): void;
+/**
+ * Removes an extended attribute from a file.
+ *
+ * @param path Path to the file
+ * @param name Name of the attribute to remove
+ */
+export declare function remove(this: V_Context, path: string, name: Name): Promise<void>;
+/**
+ * Synchronously removes an extended attribute from a file.
+ *
+ * @param path Path to the file
+ * @param name Name of the attribute to remove
+ */
+export declare function removeSync(this: V_Context, path: string, name: Name): void;
+/**
+ * Lists all extended attributes of a file.
+ *
+ * @param path Path to the file
+ * @returns Array of attribute names
+ */
+export declare function list(this: V_Context, path: string): Promise<Name[]>;
+/**
+ * Synchronously lists all extended attributes of a file.
+ *
+ * @param path Path to the file
+ * @returns Array of attribute names
+ */
+export declare function listSync(this: V_Context, path: string): Name[];

package/dist/vfs/xattr.js

@@ -0,0 +1,218 @@
+import { Buffer } from 'buffer';
+import { pick } from 'utilium';
+import { Errno, ErrnoError } from '../internal/error.js';
+import { Attributes, hasAccess } from '../internal/inode.js';
+import { normalizePath } from '../utils.js';
+import { checkAccess } from './config.js';
+import { R_OK, W_OK } from './constants.js';
+import { fixError, resolveMount } from './shared.js';
+const _allowedRestrictedNames = [];
+/**
+ * Check permission for the attribute name.
+ * For now, only attributes in the 'user' namespace are supported.
+ * @throws EPERM for attributes in namespaces other than 'user'
+ */
+function checkName($, name, path, syscall) {
+    if (!name.startsWith('user.') && !_allowedRestrictedNames.includes(name))
+        throw new ErrnoError(Errno.EPERM, 'Only attributes in the user namespace are supported', path, syscall);
+}
+export async function get(path, name, opt = {}) {
+    var _a;
+    path = normalizePath(path);
+    const { fs, path: resolved } = resolveMount(path, this);
+    checkName(this, name, path, 'xattr.get');
+    try {
+        const inode = await fs.stat(resolved);
+        if (checkAccess && !hasAccess(this, inode, R_OK)) {
+            throw ErrnoError.With('EACCES', resolved, 'xattr.get');
+        }
+        (_a = inode.attributes) !== null && _a !== void 0 ? _a : (inode.attributes = new Attributes());
+        const attr = inode.attributes.get(name);
+        if (!attr)
+            throw ErrnoError.With('ENODATA', resolved, 'xattr.get');
+        const buffer = Buffer.from(attr.value);
+        return opt.encoding == 'buffer' || !opt.encoding ? buffer : buffer.toString(opt.encoding);
+    }
+    catch (e) {
+        throw fixError(e, { [resolved]: path });
+    }
+}
+export function getSync(path, name, opt = {}) {
+    var _a;
+    path = normalizePath(path);
+    checkName(this, name, path, 'xattr.get');
+    const { fs, path: resolved } = resolveMount(path, this);
+    try {
+        const inode = fs.statSync(resolved);
+        if (checkAccess && !hasAccess(this, inode, R_OK)) {
+            throw ErrnoError.With('EACCES', resolved, 'xattr.get');
+        }
+        (_a = inode.attributes) !== null && _a !== void 0 ? _a : (inode.attributes = new Attributes());
+        const attr = inode.attributes.get(name);
+        if (!attr)
+            throw ErrnoError.With('ENODATA', resolved, 'xattr.get');
+        const buffer = Buffer.from(attr.value);
+        return opt.encoding == 'buffer' || !opt.encoding ? buffer : buffer.toString(opt.encoding);
+    }
+    catch (e) {
+        throw fixError(e, { [resolved]: path });
+    }
+}
+/**
+ * Sets the value of an extended attribute.
+ *
+ * @param path Path to the file
+ * @param name Name of the attribute to set
+ * @param value Value to set
+ * @param opt Options for the operation
+ */
+export async function set(path, name, value, opt = {}) {
+    var _a;
+    path = normalizePath(path);
+    const { fs, path: resolved } = resolveMount(path, this);
+    checkName(this, name, path, 'xattr.set');
+    try {
+        const inode = await fs.stat(resolved);
+        if (checkAccess && !hasAccess(this, inode, W_OK)) {
+            throw ErrnoError.With('EACCES', resolved, 'xattr.set');
+        }
+        (_a = inode.attributes) !== null && _a !== void 0 ? _a : (inode.attributes = new Attributes());
+        const attr = inode.attributes.get(name);
+        if (opt.create && attr) {
+            throw ErrnoError.With('EEXIST', resolved, 'xattr.set');
+        }
+        if (opt.replace && !attr) {
+            throw ErrnoError.With('ENODATA', resolved, 'xattr.set');
+        }
+        inode.attributes.set(name, Buffer.from(value));
+        await fs.touch(resolved, pick(inode, 'attributes'));
+    }
+    catch (e) {
+        throw fixError(e, { [resolved]: path });
+    }
+}
+/**
+ * Synchronously sets the value of an extended attribute.
+ *
+ * @param path Path to the file
+ * @param name Name of the attribute to set
+ * @param value Value to set
+ * @param opt Options for the operation
+ */
+export function setSync(path, name, value, opt = {}) {
+    var _a;
+    path = normalizePath(path);
+    const { fs, path: resolved } = resolveMount(path, this);
+    checkName(this, name, path, 'xattr.set');
+    try {
+        const inode = fs.statSync(resolved);
+        if (checkAccess && !hasAccess(this, inode, W_OK)) {
+            throw ErrnoError.With('EACCES', resolved, 'xattr.set');
+        }
+        (_a = inode.attributes) !== null && _a !== void 0 ? _a : (inode.attributes = new Attributes());
+        const attr = inode.attributes.get(name);
+        if (opt.create && attr) {
+            throw ErrnoError.With('EEXIST', resolved, 'xattr.set');
+        }
+        if (opt.replace && !attr) {
+            throw ErrnoError.With('ENODATA', resolved, 'xattr.set');
+        }
+        inode.attributes.set(name, Buffer.from(value));
+        fs.touchSync(resolved, pick(inode, 'attributes'));
+    }
+    catch (e) {
+        throw fixError(e, { [resolved]: path });
+    }
+}
+/**
+ * Removes an extended attribute from a file.
+ *
+ * @param path Path to the file
+ * @param name Name of the attribute to remove
+ */
+export async function remove(path, name) {
+    var _a;
+    path = normalizePath(path);
+    const { fs, path: resolved } = resolveMount(path, this);
+    checkName(this, name, path, 'xattr.remove');
+    try {
+        const inode = await fs.stat(resolved);
+        if (checkAccess && !hasAccess(this, inode, W_OK)) {
+            throw ErrnoError.With('EACCES', resolved, 'xattr.remove');
+        }
+        (_a = inode.attributes) !== null && _a !== void 0 ? _a : (inode.attributes = new Attributes());
+        const attr = inode.attributes.get(name);
+        if (!attr)
+            throw ErrnoError.With('ENODATA', resolved, 'xattr.remove');
+        inode.attributes.remove(name);
+        await fs.touch(resolved, pick(inode, 'attributes'));
+    }
+    catch (e) {
+        throw fixError(e, { [resolved]: path });
+    }
+}
+/**
+ * Synchronously removes an extended attribute from a file.
+ *
+ * @param path Path to the file
+ * @param name Name of the attribute to remove
+ */
+export function removeSync(path, name) {
+    var _a;
+    path = normalizePath(path);
+    const { fs, path: resolved } = resolveMount(path, this);
+    checkName(this, name, path, 'xattr.remove');
+    try {
+        const inode = fs.statSync(resolved);
+        if (checkAccess && !hasAccess(this, inode, W_OK)) {
+            throw ErrnoError.With('EACCES', resolved, 'xattr.remove');
+        }
+        (_a = inode.attributes) !== null && _a !== void 0 ? _a : (inode.attributes = new Attributes());
+        const attr = inode.attributes.get(name);
+        if (!attr)
+            throw ErrnoError.With('ENODATA', resolved, 'xattr.remove');
+        inode.attributes.remove(name);
+        fs.touchSync(resolved, pick(inode, 'attributes'));
+    }
+    catch (e) {
+        throw fixError(e, { [resolved]: path });
+    }
+}
+/**
+ * Lists all extended attributes of a file.
+ *
+ * @param path Path to the file
+ * @returns Array of attribute names
+ */
+export async function list(path) {
+    path = normalizePath(path);
+    const { fs, path: resolved } = resolveMount(path, this);
+    try {
+        const inode = await fs.stat(resolved);
+        if (!inode.attributes)
+            return [];
+        return inode.attributes.keys();
+    }
+    catch (e) {
+        throw fixError(e, { [resolved]: path });
+    }
+}
+/**
+ * Synchronously lists all extended attributes of a file.
+ *
+ * @param path Path to the file
+ * @returns Array of attribute names
+ */
+export function listSync(path) {
+    path = normalizePath(path);
+    const { fs, path: resolved } = resolveMount(path, this);
+    try {
+        const inode = fs.statSync(resolved);
+        if (!inode.attributes)
+            return [];
+        return inode.attributes.keys();
+    }
+    catch (e) {
+        throw fixError(e, { [resolved]: path });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zenfs/core",
-	"version": "1.11.4",
+	"version": "2.0.0",
 	"description": "A filesystem, anywhere",
 	"funding": {
 		"type": "individual",
@@ -67,11 +67,11 @@
 		"prepublishOnly": "npm run build"
 	},
 	"dependencies": {
-		"@types/node": "^22.10.1",
+		"@types/node": "^22.10.1 <22.13.7",
 		"buffer": "^6.0.3",
 		"eventemitter3": "^5.0.1",
 		"readable-stream": "^4.5.2",
-		"utilium": "^1.3.3"
+		"utilium": "^1.8.0"
 	},
 	"devDependencies": {
 		"@eslint/js": "^9.8.0",

package/readme.md

@@ -7,7 +7,7 @@ ZenFS is a cross-platform library that emulates the [NodeJS filesystem API](http
 ZenFS is modular and extensible. The core includes some built-in backends:
 
 - `InMemory`: Stores files in-memory. This is cleared when the runtime ends (e.g. a user navigating away from a web page or a Node process exiting)
-- `Overlay`: Use a read-only file system as read-write by overlaying a writable file system on top of it. ([copy-on-write](https://en.wikipedia.org/wiki/Copy-on-write))
+- `CopyOnWrite`: Use readable and writable file systems with ([copy-on-write](https://en.wikipedia.org/wiki/Copy-on-write)).
 - `Fetch`: Downloads files over HTTP with the `fetch` API
 - `Port`: Interacts with a remote over a `MessagePort`-like interface (e.g. a worker)
 - `Passthrough`: Use an existing `node:fs` interface with ZenFS

package/tests/backend/config.worker.js

@@ -1,5 +1,8 @@
 import { parentPort } from 'node:worker_threads';
-import { resolveRemoteMount } from '../../dist/backends/port/fs.js';
+import { resolveRemoteMount } from '../../dist/backends/port.js';
 import { InMemory } from '../../dist/backends/memory.js';
+import { setupLogs } from '../logs.js';
+
+setupLogs('<config>');
 
 await resolveRemoteMount(parentPort, { backend: InMemory });

package/tests/backend/fetch.test.ts

@@ -4,6 +4,9 @@ import { suite, test } from 'node:test';
 import { Worker } from 'node:worker_threads';
 import { Fetch, configureSingle, fs, mounts, type FetchFS } from '../../dist/index.js';
 import { baseUrl, defaultEntries, indexPath, whenServerReady } from '../fetch/config.js';
+import { setupLogs } from '../logs.js';
+
+setupLogs();
 
 const server = new Worker(join(import.meta.dirname, '../fetch/server.js'));
 

package/tests/backend/port.test.ts

@@ -1,10 +1,11 @@
 import assert from 'node:assert/strict';
 import { suite, test } from 'node:test';
 import { MessageChannel, Worker } from 'node:worker_threads';
-import { Port, attachFS } from '../../dist/backends/port/fs.js';
-import { waitOnline } from '../../dist/backends/port/rpc.js';
+import { Port, attachFS, waitOnline } from '../../dist/backends/port.js';
 import type { InMemoryStore, StoreFS } from '../../dist/index.js';
-import { ErrnoError, InMemory, configure, configureSingle, fs, resolveMountConfig } from '../../dist/index.js';
+import { InMemory, configure, configureSingle, fs, resolveMountConfig } from '../../dist/index.js';
+import { setupLogs } from '../logs.js';
+setupLogs();
 
 // Tests a mis-configured `Port` using a MessageChannel
 
@@ -12,36 +13,21 @@ const timeoutChannel = new MessageChannel();
 timeoutChannel.port2.unref();
 
 await suite('Timeout', { timeout: 1000 }, () => {
-	test('Misconfiguration', async () => {
-		let error: ErrnoError;
-		try {
-			await configure({
-				mounts: {
-					'/tmp-timeout': { backend: InMemory, name: 'tmp' },
-					'/port': { backend: Port, port: timeoutChannel.port1, timeout: 100 },
-				},
-			});
-		} catch (e) {
-			assert(e instanceof ErrnoError);
-			error = e;
-		}
-		assert(error! instanceof ErrnoError);
-		assert.equal(error.code, 'EIO');
-		assert(error.message.includes('RPC Failed'));
+	test('Misconfiguration', () => {
+		const configured = configure({
+			mounts: {
+				'/tmp-timeout': { backend: InMemory, label: 'tmp' },
+				'/port': { backend: Port, port: timeoutChannel.port1, timeout: 100 },
+			},
+		});
+
+		assert.rejects(configured, { code: 'EIO', message: /RPC Failed/ });
 	});
 
-	test('Remote not attached', async () => {
-		let error: ErrnoError;
-		try {
-			await configureSingle({ backend: Port, port: timeoutChannel.port1, timeout: 100 });
-			await fs.promises.writeFile('/test', 'anything');
-		} catch (e) {
-			assert(e instanceof ErrnoError);
-			error = e;
-		}
-		assert(error! instanceof ErrnoError);
-		assert.equal(error.code, 'EIO');
-		assert(error.message.includes('RPC Failed'));
+	test('Remote not attached', () => {
+		const configured = configureSingle({ backend: Port, port: timeoutChannel.port1, timeout: 100 });
+
+		assert.rejects(configured, { code: 'EIO', message: /RPC Failed/ });
 	});
 });
 
@@ -56,7 +42,7 @@ await suite('Remote FS with resolveRemoteMount', () => {
 	const content = 'FS is in a port';
 
 	test('Configuration', async () => {
-		await configureSingle({ backend: Port, port: configPort, timeout: 100 });
+		await configureSingle({ backend: Port, port: configPort, timeout: 500 });
 	});
 
 	test('Write', async () => {
@@ -79,9 +65,9 @@ let tmpfs: StoreFS<InMemoryStore>;
 
 await suite('FS with MessageChannel', () => {
 	test('configuration', async () => {
-		tmpfs = await resolveMountConfig({ backend: InMemory, name: 'tmp' });
+		tmpfs = await resolveMountConfig({ backend: InMemory, label: 'tmp' });
 		attachFS(channel.port2, tmpfs);
-		await configureSingle({ backend: Port, port: channel.port1, disableAsyncCache: true, timeout: 100 });
+		await configureSingle({ backend: Port, port: channel.port1, disableAsyncCache: true, timeout: 500 });
 	});
 
 	test('write', async () => {
@@ -116,7 +102,7 @@ await suite('Remote FS', () => {
 	const content = 'FS is in a port';
 
 	test('Configuration', async () => {
-		await configureSingle({ backend: Port, port: remotePort, timeout: 100 });
+		await configureSingle({ backend: Port, port: remotePort, timeout: 500 });
 	});
 
 	test('Write', async () => {

package/tests/backend/remote.worker.js

@@ -1,5 +1,8 @@
 import { parentPort } from 'node:worker_threads';
-import { attachFS } from '../../dist/backends/port/fs.js';
+import { attachFS } from '../../dist/backends/port.js';
 import { mounts } from '../../dist/index.js';
+import { setupLogs } from '../logs.js';
+
+setupLogs('<remote>');
 
 attachFS(parentPort, mounts.get('/'));

package/tests/backend/single-buffer.test.ts

@@ -0,0 +1,24 @@
+import { test, suite } from 'node:test';
+import { fs, mount, resolveMountConfig, SingleBuffer, umount } from '../../dist/index.js';
+import assert from 'node:assert';
+
+await suite('SingleBuffer', () => {
+	test('should be able to restore filesystem (with same metadata) from original buffer', async () => {
+		const buffer = new ArrayBuffer(0x100000);
+
+		umount('/');
+		const writable = await resolveMountConfig({ backend: SingleBuffer, buffer });
+		mount('/', writable);
+
+		fs.writeFileSync('/example.ts', 'console.log("hello world")', 'utf-8');
+		const stats = fs.statSync('/example.ts');
+
+		umount('/');
+		const snapshot = await resolveMountConfig({ backend: SingleBuffer, buffer });
+		mount('/', snapshot);
+
+		const snapshotStats = fs.statSync('/example.ts');
+
+		assert.deepEqual(snapshotStats, stats);
+	});
+});

package/tests/common/context.test.ts

@@ -5,7 +5,7 @@ import * as fs from '../../dist/vfs/index.js';
 import { canary } from 'utilium';
 
 fs.mkdirSync('/ctx');
-const { fs: ctx } = bindContext('/ctx');
+const { fs: ctx } = bindContext({ root: '/ctx' });
 
 suite('Context', () => {
 	test('create a file', () => {

package/tests/common/handle.test.ts

@@ -1,25 +1,21 @@
 import assert from 'node:assert/strict';
 import { suite, test } from 'node:test';
+import { wait } from 'utilium';
 import { constants, type FileHandle, open } from '../../dist/vfs/promises.js';
 
 const content = 'The cake is a lie',
 	appended = '\nAnother lie';
 
-await suite('FileHandle', () => {
-	let handle: FileHandle;
-	const filePath = './test.txt';
-
-	test('open', async () => {
-		handle = await open(filePath, 'w+');
-	});
+await using handle: FileHandle = await open('./test.txt', 'ws+');
 
+await suite('FileHandle', () => {
 	test('writeFile', async () => {
 		await handle.writeFile(content);
 		await handle.sync();
 	});
 
 	test('readFile', async () => {
-		assert((await handle.readFile('utf8')) === content);
+		assert.equal(await handle.readFile('utf8'), content);
 	});
 
 	test('appendFile', async () => {
@@ -27,12 +23,12 @@ await suite('FileHandle', () => {
 	});
 
 	test('readFile after appendFile', async () => {
-		assert((await handle.readFile({ encoding: 'utf8' })) === content + appended);
+		assert.equal(await handle.readFile({ encoding: 'utf8' }), content + appended);
 	});
 
 	test('truncate', async () => {
 		await handle.truncate(5);
-		assert((await handle.readFile({ encoding: 'utf8' })) === content.slice(0, 5));
+		assert.equal(await handle.readFile({ encoding: 'utf8' }), content.slice(0, 5));
 	});
 
 	test('stat', async () => {
@@ -54,7 +50,16 @@ await suite('FileHandle', () => {
 		assert.equal(stats.gid, 5678);
 	});
 
-	test('close', async () => {
-		await handle.close();
+	test('readLines', async () => {
+		await handle.writeFile('first line\nsecond line\nthird line');
+
+		await using rl = handle.readLines();
+
+		const lines: string[] = [];
+		rl.on('line', (line: string) => lines.push(line));
+
+		await wait(50);
+
+		assert.deepEqual(lines, ['first line', 'second line', 'third line']);
 	});
 });

package/tests/common/path.test.ts

@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict';
 import { suite, test } from 'node:test';
-import { basename, dirname, extname, join, normalize, resolve } from '../../dist/vfs/path.js';
+import { basename, dirname, extname, join, normalize, resolve } from '../../dist/path.js';
 import * as fs from '../../dist/vfs/index.js';
 
 suite('Path emulation', () => {