@zenfs/core 2.7.7 → 2.8.0

package/dist/vfs/async.js

@@ -53,10 +53,10 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
 import { rethrow, setUVMessage, UV } from 'kerium';
 import { decodeUTF8 } from 'utilium';
 import * as constants from '../constants.js';
-import { contextOf } from '../internal/contexts.js';
+import { applyUmask, contextOf } from '../internal/contexts.js';
 import { assertRemovable, assertSearchable, hasAccess, isDirectory, isSymbolicLink } from '../internal/inode.js';
 import { basename, dirname, join, parse, resolve as resolvePath } from '../path.js';
-import { normalizeMode, normalizePath } from '../utils.js';
+import { normalizeMode, normalizePath, normalizeTime } from '../utils.js';
 import { checkAccess, resolveFullWalk } from './config.js';
 import { Dirent, ifToDt } from './dir.js';
 import { Handle } from './file.js';
@@ -144,7 +144,7 @@ export async function open($, path, opt) {
             if (!stats) {
                 const { euid: uid, egid: gid } = contextOf($).credentials;
                 const inode = await fs.createFile(resolved, {
-                    mode,
+                    mode: applyUmask($, mode),
                     uid: parentStats.mode & constants.S_ISUID ? parentStats.uid : uid,
                     gid: parentStats.mode & constants.S_ISGID ? parentStats.gid : gid,
                 });
@@ -164,7 +164,7 @@ export async function open($, path, opt) {
         throw UV('EACCES', $ex);
     if (flag & constants.O_EXCL)
         throw UV('EEXIST', $ex);
-    if (!opt.allowDirectory && isDirectory({ mode }))
+    if (!opt.allowDirectory && isDirectory(stats))
         throw UV('EISDIR', 'open', path);
     const handle = new Handle($, path, resolved, flag, cache.ref(resolved, stats));
     if (flag & constants.O_TRUNC)
@@ -189,7 +189,8 @@ export async function readlink(path) {
 export async function mkdir(path, options = {}) {
     const original = normalizePath.call(this, path);
     const { euid: uid, egid: gid } = contextOf(this).credentials;
-    const { mode = 0o777, recursive } = options;
+    const { recursive } = options;
+    const mode = applyUmask(this, options.mode ?? 0o777);
     const $ex = { syscall: 'mkdir', path: original };
     const { fullPath: realParent } = await resolve(this, dirname(original), false, $ex);
     const { fs, cache, path: target } = resolveMount(join(realParent, basename(original)), this, $ex);
@@ -400,3 +401,69 @@ export async function stat(path, lstat) {
         throw UV('ENOENT', extra);
     return stats;
 }
+/**
+ * Opens a handle for changing metadata, which does not need read or write access to the file.
+ */
+async function _openMetadata($, path, syscall, noFollow) {
+    const { fullPath, cache, path: resolved, stats } = await resolve($, path, noFollow, { syscall });
+    if (!stats)
+        throw UV('ENOENT', syscall, path);
+    return new Handle($, fullPath, resolved, constants.O_RDONLY, cache.ref(resolved, stats));
+}
+export async function chmod(path, mode, noFollow) {
+    const env_6 = { stack: [], error: void 0, hasError: false };
+    try {
+        path = normalizePath.call(this, path);
+        const numMode = normalizeMode(mode, -1);
+        if (numMode < 0)
+            throw UV('EINVAL', 'chmod', path);
+        const handle = __addDisposableResource(env_6, await _openMetadata(this, path, 'chmod', noFollow), true);
+        await handle.chmod(numMode);
+        emitChange(this, 'change', handle.path);
+    }
+    catch (e_6) {
+        env_6.error = e_6;
+        env_6.hasError = true;
+    }
+    finally {
+        const result_1 = __disposeResources(env_6);
+        if (result_1)
+            await result_1;
+    }
+}
+export async function chown(path, uid, gid, noFollow) {
+    const env_7 = { stack: [], error: void 0, hasError: false };
+    try {
+        path = normalizePath.call(this, path);
+        const handle = __addDisposableResource(env_7, await _openMetadata(this, path, 'chown', noFollow), true);
+        await handle.chown(uid, gid);
+        emitChange(this, 'change', handle.path);
+    }
+    catch (e_7) {
+        env_7.error = e_7;
+        env_7.hasError = true;
+    }
+    finally {
+        const result_2 = __disposeResources(env_7);
+        if (result_2)
+            await result_2;
+    }
+}
+export async function utimes(path, atime, mtime, noFollow) {
+    const env_8 = { stack: [], error: void 0, hasError: false };
+    try {
+        path = normalizePath.call(this, path);
+        const handle = __addDisposableResource(env_8, await _openMetadata(this, path, 'utimes', noFollow), true);
+        await handle.utimes(normalizeTime(atime), normalizeTime(mtime));
+        emitChange(this, 'change', handle.path);
+    }
+    catch (e_8) {
+        env_8.error = e_8;
+        env_8.hasError = true;
+    }
+    finally {
+        const result_3 = __disposeResources(env_8);
+        if (result_3)
+            await result_3;
+    }
+}

package/dist/vfs/sync.d.ts

@@ -1,4 +1,4 @@
-import type { PathLike } from 'node:fs';
+import type { Mode, PathLike, TimeLike } from 'node:fs';
 import type { V_Context } from '../context.js';
 import type { InodeLike } from '../internal/inode.js';
 import type { MkdirOptions, OpenOptions, ReaddirOptions, ResolvedPath } from './shared.js';
@@ -23,3 +23,6 @@ export declare function readdir(this: V_Context, path: PathLike, options?: Readd
 export declare function rename(this: V_Context, oldPath: PathLike, newPath: PathLike): void;
 export declare function link(this: V_Context, target: PathLike, link: PathLike): void;
 export declare function stat(this: V_Context, path: PathLike, lstat: boolean): InodeLike;
+export declare function chmod(this: V_Context, path: PathLike, mode: Mode, noFollow?: boolean): void;
+export declare function chown(this: V_Context, path: PathLike, uid: number, gid: number, noFollow?: boolean): void;
+export declare function utimes(this: V_Context, path: PathLike, atime: TimeLike, mtime: TimeLike, noFollow?: boolean): void;

package/dist/vfs/sync.js

@@ -53,11 +53,11 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
 import { setUVMessage, UV } from 'kerium';
 import { decodeUTF8 } from 'utilium';
 import * as constants from '../constants.js';
-import { contextOf } from '../internal/contexts.js';
+import { applyUmask, contextOf } from '../internal/contexts.js';
 import { wrap } from '../internal/error.js';
 import { assertRemovable, assertSearchable, hasAccess, isDirectory, isSymbolicLink } from '../internal/inode.js';
 import { basename, dirname, join, parse, resolve as resolvePath } from '../path.js';
-import { normalizeMode, normalizePath } from '../utils.js';
+import { normalizeMode, normalizePath, normalizeTime } from '../utils.js';
 import { cacheOf } from './vcache.js';
 import { checkAccess, resolveFullWalk } from './config.js';
 import { Dirent, ifToDt } from './dir.js';
@@ -156,7 +156,7 @@ export function open($, path, opt) {
             const _ = __addDisposableResource(env_1, cache.lockSync(parentPath, 'rw', parentStats), false);
             const { euid: uid, egid: gid } = contextOf($).credentials;
             const inode = fs.createFileSync(resolved, {
-                mode,
+                mode: applyUmask($, mode),
                 uid: parentStats.mode & constants.S_ISUID ? parentStats.uid : uid,
                 gid: parentStats.mode & constants.S_ISGID ? parentStats.gid : gid,
             });
@@ -205,7 +205,8 @@ export function mkdir(path, options = {}) {
     const { fs, cache, path: target } = resolveMount(join(realParent, basename(original)), this, $ex);
     const followed = realParent != dirname(original);
     const { euid: uid, egid: gid } = contextOf(this).credentials;
-    const { mode = 0o777, recursive } = options;
+    const { recursive } = options;
+    const mode = applyUmask(this, options.mode ?? 0o777);
     let firstCreated;
     const __create = (path, resolved) => {
         const env_2 = { stack: [], error: void 0, hasError: false };
@@ -427,3 +428,63 @@ export function stat(path, lstat) {
         throw UV('ENOENT', extra);
     return stats;
 }
+/**
+ * Opens a handle for changing metadata, which does not need read or write access to the file.
+ */
+function _openMetadata($, path, syscall, noFollow) {
+    const { fullPath, cache, path: resolved, stats } = resolve($, path, noFollow, { syscall });
+    if (!stats)
+        throw UV('ENOENT', syscall, path);
+    return new Handle($, fullPath, resolved, constants.O_RDONLY, cache.ref(resolved, stats));
+}
+export function chmod(path, mode, noFollow) {
+    const env_6 = { stack: [], error: void 0, hasError: false };
+    try {
+        path = normalizePath.call(this, path);
+        const numMode = normalizeMode(mode, -1);
+        if (numMode < 0)
+            throw UV('EINVAL', 'chmod', path);
+        const handle = __addDisposableResource(env_6, _openMetadata(this, path, 'chmod', noFollow), false);
+        handle.chmodSync(numMode);
+        emitChange(this, 'change', handle.path);
+    }
+    catch (e_6) {
+        env_6.error = e_6;
+        env_6.hasError = true;
+    }
+    finally {
+        __disposeResources(env_6);
+    }
+}
+export function chown(path, uid, gid, noFollow) {
+    const env_7 = { stack: [], error: void 0, hasError: false };
+    try {
+        path = normalizePath.call(this, path);
+        const handle = __addDisposableResource(env_7, _openMetadata(this, path, 'chown', noFollow), false);
+        handle.chownSync(uid, gid);
+        emitChange(this, 'change', handle.path);
+    }
+    catch (e_7) {
+        env_7.error = e_7;
+        env_7.hasError = true;
+    }
+    finally {
+        __disposeResources(env_7);
+    }
+}
+export function utimes(path, atime, mtime, noFollow) {
+    const env_8 = { stack: [], error: void 0, hasError: false };
+    try {
+        path = normalizePath.call(this, path);
+        const handle = __addDisposableResource(env_8, _openMetadata(this, path, 'utimes', noFollow), false);
+        handle.utimesSync(normalizeTime(atime), normalizeTime(mtime));
+        emitChange(this, 'change', handle.path);
+    }
+    catch (e_8) {
+        env_8.error = e_8;
+        env_8.hasError = true;
+    }
+    finally {
+        __disposeResources(env_8);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zenfs/core",
-	"version": "2.7.7",
+	"version": "2.8.0",
 	"description": "A filesystem, anywhere",
 	"funding": {
 		"type": "individual",
@@ -79,7 +79,7 @@
 		"buffer": "^6.0.3",
 		"eventemitter3": "^5.0.1",
 		"kerium": "^1.5.0",
-		"memium": "^1.0.0",
+		"memium": "^1.1.0",
 		"utilium": "^3.7.0"
 	},
 	"devDependencies": {

package/tests/backend/single-buffer-rotate.worker.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
 import { parentPort, workerData } from 'node:worker_threads';
-import { SuperBlock } from '../../dist/backends/single_buffer.js';
+import { SuperBlock } from '../../dist/backends/single_buffer/v1.js';
 import { setupLogs } from '../logs.js';
 
 setupLogs('<worker>');

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

@@ -0,0 +1,342 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+import { fs, mount, resolveMountConfig, SingleBuffer, vfs } from '@zenfs/core';
+import { SingleBufferStore } from '@zenfs/core/backends/single_buffer/v1';
+import { SingleBufferStore as SingleBufferStoreV2, SuperBlock } from '@zenfs/core/backends/single_buffer/v2';
+import { Mutex } from 'memium/locks';
+import assert from 'node:assert/strict';
+import { randomBytes } from 'node:crypto';
+import { suite, test } from 'node:test';
+import { Worker } from 'worker_threads';
+import { setupLogs } from '../logs.js';
+
+setupLogs();
+
+function runWorker(workerData: object): Promise<unknown> {
+	const worker = new Worker(import.meta.dirname + '/single-buffer-v2.worker.js', { workerData });
+	const { promise, resolve, reject } = Promise.withResolvers<unknown>();
+	const timeout = setTimeout(() => reject(new Error('worker timed out')), 5000);
+	worker.on('error', reject);
+	worker.on('message', message => (message instanceof Error ? reject(message) : resolve(message)));
+	return promise.finally(() => {
+		clearTimeout(timeout);
+		void worker.terminate();
+		worker.unref();
+	});
+}
+
+let mounts = 0;
+
+/** Mounts a SingleBuffer on a unique mount point */
+async function mountBuffer(buffer: ArrayBufferLike): Promise<[path: string, umount: () => void]> {
+	const path = `/sbfs-v2-${mounts++}`;
+	mount(path, await resolveMountConfig({ backend: SingleBuffer, buffer, v2: true }));
+	return [path, () => vfs.umount(path)];
+}
+
+/** Bytes not available for new data */
+function used(path: string): number {
+	const { blocks, bfree, bsize } = fs.statfsSync(path);
+	return (blocks - bfree) * bsize;
+}
+
+await suite('SingleBuffer v2', () => {
+	test('filesystem restoration from original buffer (with same metadata)', async () => {
+		const buffer = new ArrayBuffer(0x100000);
+
+		const [path, umount] = await mountBuffer(buffer);
+		fs.writeFileSync(path + '/example.ts', 'console.log("hello world")', 'utf-8');
+		const stats = fs.statSync(path + '/example.ts');
+
+		const [snapshot, umountSnapshot] = await mountBuffer(buffer);
+		assert.deepEqual(fs.statSync(snapshot + '/example.ts'), stats);
+
+		umount();
+		umountSnapshot();
+	});
+
+	test('cross-thread SharedArrayBuffer', async () => {
+		const buffer = new SharedArrayBuffer(0x100000);
+		const [path, umount] = await mountBuffer(buffer);
+
+		assert.equal(await runWorker({ buffer }), 'continue');
+		assert(fs.existsSync(path + '/worker-file.ts'));
+
+		umount();
+	});
+
+	test('concurrent writers allocate distinct IDs', async () => {
+		const buffer = new SharedArrayBuffer(0x1000000);
+		const [path, umount] = await mountBuffer(buffer);
+
+		const count = 50,
+			workers = 4;
+		for (let id = 0; id < workers; id++) fs.mkdirSync(`${path}/w${id}`);
+
+		const results = await Promise.all(Array.from({ length: workers }, (_, id) => runWorker({ buffer, mode: 'write', id, count })));
+		assert.deepEqual(results, Array(workers).fill('continue'));
+
+		const [check, umountCheck] = await mountBuffer(buffer);
+		const inodes = new Set<number>();
+		for (let id = 0; id < workers; id++) {
+			for (let i = 0; i < count; i++) {
+				const file = `${check}/w${id}/${i}`;
+				assert.equal(fs.readFileSync(file, 'utf8'), `worker ${id} file ${i}`);
+				inodes.add(fs.statSync(file).ino);
+			}
+		}
+		assert.equal(inodes.size, workers * count);
+
+		umount();
+		umountCheck();
+	});
+
+	test('readers see whole versions while another thread writes', async () => {
+		const buffer = new SharedArrayBuffer(0x1000000);
+		const store = new SingleBufferStoreV2(buffer, 0, undefined, { format: true });
+
+		store.set(100, new Uint8Array(1000).fill(1));
+		const gate = new Int32Array(new SharedArrayBuffer(4));
+		const reader = runWorker({ buffer, gate, mode: 'read' });
+		Atomics.wait(gate, 0, 0, 5000);
+
+		for (let i = 0; i < 2000; i++) store.set(100, new Uint8Array(1000 + ((i * 7919) % 50000)).fill(i % 255 || 1));
+		store.set(101, new Uint8Array(1));
+
+		assert.ok(((await reader) as number) > 0, 'the reader never read anything');
+	});
+
+	test('threads creating the same file system at once share it', async () => {
+		const buffer = new SharedArrayBuffer(0x400000);
+		const uuids = await Promise.all(Array.from({ length: 4 }, () => runWorker({ buffer, mode: 'setup' })));
+		assert.equal(new Set(uuids).size, 1);
+		assert.equal(Buffer.from(new SuperBlock(buffer, 0).uuid).toString('hex'), uuids[0]);
+	});
+
+	test('partial reads and writes', () => {
+		const store = new SingleBufferStoreV2(new ArrayBuffer(0x100000), 0, undefined, { format: true });
+		store.set(10, new Uint8Array([1, 2, 3, 4]));
+		assert.deepEqual(store.get(10, 1, 3), new Uint8Array([2, 3]));
+		assert.deepEqual(store.get(10, 2), new Uint8Array([3, 4]));
+
+		store.set(10, new Uint8Array([9]), 2);
+		assert.deepEqual(store.get(10), new Uint8Array([1, 2, 9, 4]));
+
+		store.set(10, new Uint8Array([7]), 6);
+		assert.deepEqual(store.get(10), new Uint8Array([1, 2, 9, 4, 0, 0, 7]));
+
+		store.set(10, new Uint8Array([5]));
+		assert.deepEqual(store.get(10), new Uint8Array([5]));
+
+		store.set(11, new Uint8Array([8]), 2);
+		assert.deepEqual(store.get(11), new Uint8Array([0, 0, 8]));
+	});
+
+	test('appended data is rarely moved', () => {
+		const store = new SingleBufferStoreV2(new ArrayBuffer(0x100000), 0, undefined, { format: true });
+		const offsetOf = (id: number) => store['read'](index => index.get(BigInt(id))!.offset);
+
+		store.set(10, new Uint8Array(100).fill(1));
+		let moves = 0;
+		for (let i = 0; i < 200; i++) {
+			const before = offsetOf(10);
+			store.set(10, new Uint8Array(100).fill(i + 2), 100 + i * 100);
+			if (offsetOf(10) != before) moves++;
+		}
+
+		// Capacity grows by half each time data moves
+		assert.ok(moves <= Math.ceil(Math.log(201) / Math.log(1.5)), `data moved ${moves} times`);
+
+		const data = store.get(10)!;
+		assert.equal(data.length, 20100);
+		assert.ok(data.subarray(0, 100).every(byte => byte == 1));
+		assert.ok(data.subarray(20000).every(byte => byte == 201));
+	});
+
+	test('writing past the end of a truncated file leaves zeros between', async () => {
+		const [path, umount] = await mountBuffer(new ArrayBuffer(0x100000));
+		fs.writeFileSync(path + '/file', Buffer.alloc(100, 1));
+		fs.truncateSync(path + '/file', 10);
+
+		const fd = fs.openSync(path + '/file', 'r+');
+		fs.writeSync(fd, Buffer.alloc(10, 2), 0, 10, 50);
+		fs.closeSync(fd);
+
+		const data = fs.readFileSync(path + '/file');
+		assert.equal(data.length, 60);
+		assert.ok(data.subarray(0, 10).every(byte => byte == 1));
+		assert.ok(data.subarray(10, 50).every(byte => byte == 0));
+		assert.ok(data.subarray(50).every(byte => byte == 2));
+		umount();
+	});
+
+	test('reuses freed space', async () => {
+		const [path, umount] = await mountBuffer(new ArrayBuffer(0x100000));
+		const baseline = used(path);
+
+		// Writes far more than the buffer can hold
+		for (let i = 0; i < 200; i++) {
+			fs.writeFileSync(path + '/churn', randomBytes(0x10000));
+			fs.appendFileSync(path + '/log', randomBytes(1024));
+			if (i % 10 == 9) fs.rmSync(path + '/log');
+		}
+		fs.rmSync(path + '/churn');
+		fs.writeFileSync(path + '/settle', '');
+		fs.rmSync(path + '/settle');
+
+		assert.ok(used(path) - baseline < 0x8000, `leaked ${used(path) - baseline} bytes`);
+		umount();
+	});
+
+	test('failed writes leave the store unchanged', () => {
+		const store = new SingleBufferStoreV2(new ArrayBuffer(0x100000), 0, undefined, { format: true });
+		store.set(10, new Uint8Array([1, 2, 3]));
+		const before = store.usage();
+
+		assert.throws(() => store.set(12, new Uint8Array(0x200000)), { code: 'ENOSPC' });
+		assert.throws(() => store.set(10, new Uint8Array(0x200000)), { code: 'ENOSPC' });
+
+		assert.deepEqual(store.get(10), new Uint8Array([1, 2, 3]));
+		assert.equal(store.get(12), undefined);
+		assert.deepEqual(store.usage(), before);
+
+		store.set(12, new Uint8Array([4]));
+		assert.deepEqual(store.get(12), new Uint8Array([4]));
+	});
+
+	test('recovers from a writer that stopped while holding the lock', async () => {
+		const buffer = new SharedArrayBuffer(0x100000);
+		const [path, umount] = await mountBuffer(buffer);
+
+		const { state_offset } = new SuperBlock(buffer, 0);
+		new Mutex(buffer, state_offset, { lease: 50 }).lock();
+
+		fs.writeFileSync(path + '/after', 'recovered');
+		assert.equal(fs.readFileSync(path + '/after', 'utf8'), 'recovered');
+		umount();
+	});
+
+	test('upgrades version 1 file systems in place', async () => {
+		const buffer = new ArrayBuffer(0x300000);
+		const v1 = '/sbfs-v1';
+		mount(v1, await resolveMountConfig({ backend: SingleBuffer, buffer, v2: false }));
+
+		// Enough files for several metadata blocks, with growth and deletion leaking space
+		fs.mkdirSync(v1 + '/dir/nested', { recursive: true });
+		const files = new Map<string, string>();
+		const deleted: string[] = [];
+		for (let i = 0; i < 300; i++) {
+			const file = (i % 3 ? '/dir/' : i % 2 ? '/dir/nested/' : '/') + 'f' + i;
+			let content = `file ${i}\n`.repeat((i % 7) + 1);
+			fs.writeFileSync(v1 + file, content);
+
+			if (i % 10 == 0) {
+				content += 'grown\n'.repeat(20);
+				fs.writeFileSync(v1 + file, content);
+			}
+
+			if (i % 25 == 0) {
+				fs.unlinkSync(v1 + file);
+				deleted.push(file);
+			} else files.set(file, content);
+		}
+
+		const stats = new Map(Array.from(files.keys(), file => [file, fs.statSync(v1 + file)]));
+		const v1Free = 0x300000 - used(v1);
+		vfs.umount(v1);
+		assert.equal(new SuperBlock(buffer, 0).version, 1);
+
+		const [path, umount] = await mountBuffer(buffer);
+		assert.equal(new SuperBlock(buffer, 0).version, 2);
+
+		for (const [file, content] of files) {
+			assert.deepEqual(fs.statSync(path + file), stats.get(file), `stats of ${file}`);
+			assert.equal(fs.readFileSync(path + file, 'utf8'), content, `content of ${file}`);
+		}
+		for (const file of deleted) assert.ok(!fs.existsSync(path + file), `${file} should have been deleted`);
+
+		// Space leaked by version 1 and its metadata blocks are reclaimed
+		fs.writeFileSync(path + '/new', 'written after upgrading');
+		fs.rmSync(path + '/new');
+		const free = 0x300000 - used(path);
+		assert.ok(free > v1Free + 0x10000, `only ${free} bytes are free after upgrading, compared to ${v1Free}`);
+
+		const [again, umountAgain] = await mountBuffer(buffer);
+		assert.equal(fs.readFileSync(again + '/dir/f1', 'utf8'), files.get('/dir/f1'));
+
+		umount();
+		umountAgain();
+	});
+
+	test('is the default, but not used for existing version 1 file systems unless asked for', async () => {
+		const version = (buffer: ArrayBufferLike) => new SuperBlock(buffer, 0).version;
+
+		const fresh = new ArrayBuffer(0x100000);
+		await resolveMountConfig({ backend: SingleBuffer, buffer: fresh });
+		assert.equal(version(fresh), 2);
+
+		const buffer = new ArrayBuffer(0x100000);
+		await resolveMountConfig({ backend: SingleBuffer, buffer, v2: false });
+		assert.equal(version(buffer), 1);
+
+		await resolveMountConfig({ backend: SingleBuffer, buffer });
+		assert.equal(version(buffer), 1);
+
+		await resolveMountConfig({ backend: SingleBuffer, buffer, v2: true });
+		assert.equal(version(buffer), 2);
+
+		mount('/sbfs-detect', await resolveMountConfig({ backend: SingleBuffer, buffer, v2: false }));
+		fs.writeFileSync('/sbfs-detect/file', 'still version 2');
+		assert.equal(version(buffer), 2);
+		vfs.umount('/sbfs-detect');
+
+		assert.throws(() => new SingleBufferStore(buffer), { code: 'EIO' });
+	});
+
+	test('reliability across varied file sizes', async () => {
+		const buffer = new ArrayBuffer(0x400000);
+		const [path, umount] = await mountBuffer(buffer);
+
+		const filePath = `${path}/payload.bin`;
+		const growthSizes = [0, 1, 17, 512, 8192, 65535, 262144, 524288];
+		const shrinkSizes = [262144, 4096, 128, 0];
+
+		const verifySnapshot = async (expected: Buffer, size: number) => {
+			const [verify, umountVerify] = await mountBuffer(buffer);
+			try {
+				const reopened = fs.readFileSync(`${verify}/payload.bin`);
+				assert.strictEqual(reopened.byteLength, size, `snapshot size mismatch for ${size} bytes`);
+				assert.deepStrictEqual(reopened, expected, `snapshot content mismatch for ${size} bytes`);
+			} finally {
+				umountVerify();
+			}
+		};
+
+		try {
+			for (const size of [...growthSizes, ...shrinkSizes]) {
+				const payload = size ? randomBytes(size) : Buffer.alloc(0);
+				fs.writeFileSync(filePath, payload);
+				const direct = fs.readFileSync(filePath);
+				assert.strictEqual(direct.byteLength, size, `direct size mismatch for ${size} bytes`);
+				assert.deepStrictEqual(direct, payload, `direct content mismatch for ${size} bytes`);
+				await verifySnapshot(direct, size);
+			}
+		} finally {
+			umount();
+		}
+	});
+
+	test('files with uneven sizes', async () => {
+		const [path, umount] = await mountBuffer(new ArrayBuffer(0x400000));
+
+		const sizes = [1, 17, 257, 3, 5, 13, 1023, 4095, 7, 9];
+		try {
+			for (let i = 0; i < 400; i++) fs.writeFileSync(`${path}/f${i}.txt`, Buffer.alloc(sizes[i % sizes.length], i & 0xff));
+			for (let i = 0; i < 400; i += 37) {
+				const expected = Buffer.alloc(sizes[i % sizes.length], i & 0xff);
+				assert.deepStrictEqual(fs.readFileSync(`${path}/f${i}.txt`), expected, `content mismatch at f${i}.txt`);
+			}
+		} finally {
+			umount();
+		}
+	});
+});

package/tests/backend/single-buffer-v2.worker.js

@@ -0,0 +1,51 @@
+import assert from 'node:assert/strict';
+import { writeFileSync as _write } from 'node:fs';
+import { parentPort, workerData } from 'node:worker_threads';
+import { SingleBufferStore as SingleBufferStoreV2, SuperBlock } from '../../dist/backends/single_buffer/v2.js';
+import { configureSingle, fs, SingleBuffer } from '../../dist/index.js';
+import { setupLogs } from '../logs.js';
+
+setupLogs('<worker>');
+
+const { buffer, gate, mode = 'create', id = 0, count = 0 } = workerData;
+
+try {
+	if (mode != 'read') await configureSingle({ backend: SingleBuffer, buffer });
+
+	switch (mode) {
+		case 'create': {
+			const content = 'console.log("this file was created by the worker")';
+			fs.writeFileSync('/worker-file.ts', content, 'utf-8');
+			assert.equal(fs.readFileSync('/worker-file.ts', 'utf-8'), content);
+			break;
+		}
+		case 'setup':
+			parentPort.postMessage(Buffer.from(new SuperBlock(buffer, 0).uuid).toString('hex'));
+			process.exit(0);
+		case 'write':
+			for (let i = 0; i < count; i++) fs.writeFileSync(`/w${id}/${i}`, `worker ${id} file ${i}`);
+			break;
+		case 'read': {
+			const store = new SingleBufferStoreV2(buffer);
+			const deadline = Date.now() + 5000;
+			let reads = 0;
+			while (!store.get(101) && Date.now() < deadline) {
+				const data = store.get(100);
+				const fill = data[0];
+				assert.ok(fill && data.every(byte => byte == fill), `read a torn version (${data.length} bytes, first ${fill})`);
+				if (!reads++) {
+					Atomics.store(gate, 0, 1);
+					Atomics.notify(gate, 0);
+				}
+			}
+			parentPort.postMessage(reads);
+			process.exit(0);
+		}
+	}
+} catch (e) {
+	if (process.env.DEBUG) _write('tmp/shared.bin', new Uint8Array(buffer));
+	console.error(e);
+	parentPort.postMessage(e);
+}
+
+parentPort.postMessage('continue');