@zenfs/core 2.4.2 → 2.4.3

package/COPYING.md

@@ -1,18 +1,24 @@
 _This document is supplemental to the license._
 
-**This is a very easy requirement, please respect it.**
-Feel free to reach out if you have any concerns regarding licensing.
+Feel free to reach out if you have any concerns regarding licensing. You can create a new discussion [here](https://github.com/orgs/zen-fs/discussions/new?category=q-a).
+
+Regarding section 4(b) of version 3 of the LGPL, you are permitted to link to a copy of the LGPL and this document rather than including the full text of both.
+
+#### Exception for web applications
 
-If you convey copies of ZenFS (including in bundles), you must meet section 4 and 5 of the license. This includes at a minimum:
+You are permitted to convey the Combined Work without meeting the requirements of section 4(d) of version 3 of the LGPL if
 
-- disclosure that ZenFS is in use
-- linking to the GitHub or npm pages
-- referencing the license and copyright.
+- a) the Combined Work is only accessed by users from other computers over a network (i.e. a web application or website), and
+- b) you also provide the [Corresponding Source](https://www.gnu.org/licenses/gpl-3.0.html#:~:text=“Corresponding%20Source”) of The Library or an offer thereof.
+
+This exception does not excuse or waive any other requirement of the LGPL.
+
+The practical goal of this exception is to allow ZenFS to be used in modern web apps. For the avoidance of doubt, you are permitted to bundle and minify ZenFS in a web application. Linking to ZenFS' GitHub or npm page is sufficient to satisfy the above section (b) provided you do not modify ZenFS.
 
 For example, in a list of libraries you could have:
 
-> - [ZenFS](https://github.com/zen-fs/core), LGPL-3.0-or-later, Copyright © James Prevett and other ZenFS contributors
+> - [ZenFS](https://github.com/zen-fs/core), Licensed under the [LGPL 3.0 or later](https://www.gnu.org/licenses/lgpl-3.0.html) and [COPYING.md](https://github.com/zen-fs/core/blob/main/COPYING.md), Copyright © James Prevett and other ZenFS contributors
 
-<br />
+**This is a very easy requirement, please respect it.**
 
 Before v2.4.0, ZenFS was licensed under the MIT. This still means you need to include the copyright notice and license.

package/dist/backends/backend.d.ts

@@ -9,7 +9,7 @@ type OptionType = 'string' | 'number' | 'bigint' | 'boolean' | 'symbol' | 'undef
  * @category Backends and Configuration
  */
 export type OptionsConfig<T> = {
-    [K in keyof T]: {
+    [K in Exclude<keyof T, keyof SharedConfig>]: {
         /**
          * The type of the option. Can be a:
          * - string given by `typeof`

package/dist/backends/single_buffer.d.ts

@@ -26,6 +26,7 @@ declare const MetadataBlock_base: import("memium/decorators").StructFromTypedArr
  */
 export declare class MetadataBlock extends MetadataBlock_base<ArrayBufferLike> {
     readonly ['constructor']: typeof MetadataBlock;
+    private static readonly lockIndex;
     /**
      * The crc32c checksum for the metadata block.
      * @privateRemarks Keep this first!
@@ -37,7 +38,6 @@ export declare class MetadataBlock extends MetadataBlock_base<ArrayBufferLike> {
     accessor previous_offset: number;
     protected _previous?: MetadataBlock;
     get previous(): MetadataBlock | undefined;
-    protected get offsetHex(): string;
     /** Metadata entries. */
     accessor items: ArrayOf<MetadataEntry>;
     toString(long?: boolean): string;

package/dist/backends/single_buffer.js

@@ -86,7 +86,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
 });
 // SPDX-License-Identifier: LGPL-3.0-or-later
 import { withErrno } from 'kerium';
-import { alert, crit, err, warn } from 'kerium/log';
+import { alert, crit, debug, err, warn } from 'kerium/log';
 import { array, offsetof, sizeof } from 'memium';
 import { $from, field, struct, types as t } from 'memium/decorators';
 import { BufferView } from 'utilium/buffer.js';
@@ -95,6 +95,7 @@ import { decodeUUID, encodeUUID } from 'utilium/string.js';
 import { _inode_version, Inode } from '../internal/inode.js';
 import { StoreFS } from './store/fs.js';
 import { SyncMapTransaction } from './store/map.js';
+const hex = (value) => '0x' + value.toString(16).padStart(8, '0');
 // eslint-disable-next-line @typescript-eslint/unbound-method
 const { format } = new Intl.NumberFormat('en-US', {
     notation: 'compact',
@@ -155,7 +156,7 @@ let MetadataEntry = (() => {
         get size() { return this.#size_accessor_storage; }
         set size(value) { this.#size_accessor_storage = value; }
         toString() {
-            return `<MetadataEntry @ 0x${this.byteOffset.toString(16).padStart(8, '0')}>`;
+            return `<MetadataEntry @ ${hex(this.byteOffset)}>`;
         }
         constructor() {
             super(...arguments);
@@ -216,8 +217,8 @@ let MetadataBlock = (() => {
             __esDecorate(null, _classDescriptor = { value: _classThis }, _classDecorators, { kind: "class", name: _classThis.name, metadata: _metadata }, null, _classExtraInitializers);
             MetadataBlock = _classThis = _classDescriptor.value;
             if (_metadata) Object.defineProperty(_classThis, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
-            __runInitializers(_classThis, _classExtraInitializers);
         }
+        static lockIndex = offsetof(MetadataBlock, 'locked') / Int32Array.BYTES_PER_ELEMENT;
         #checksum_accessor_storage = __runInitializers(this, _checksum_initializers, void 0);
         /**
          * The crc32c checksum for the metadata block.
@@ -240,27 +241,24 @@ let MetadataBlock = (() => {
             this._previous ??= new MetadataBlock(this.buffer, this.previous_offset);
             return this._previous;
         }
-        get offsetHex() {
-            return '0x' + this.byteOffset.toString(16).padStart(8, '0');
-        }
         #items_accessor_storage = __runInitializers(this, _items_initializers, void 0);
         /** Metadata entries. */
         get items() { return this.#items_accessor_storage; }
         set items(value) { this.#items_accessor_storage = value; }
         toString(long = false) {
             if (!long)
-                return `<MetadataBlock @ ${this.offsetHex}>`;
+                return `<MetadataBlock @ ${hex(this.byteOffset)}>`;
             let text = [
-                `---- Metadata block at ${this.offsetHex} ----`,
-                `Checksum: 0x${this.checksum.toString(16).padStart(8, '0')}`,
+                `---- Metadata block at ${hex(this.byteOffset)} ----`,
+                `Checksum: ${hex(this.checksum)}`,
                 `Last updated: ${new Date(Number(this.timestamp)).toLocaleString()}`,
-                `Previous block: 0x${this.previous_offset.toString(16).padStart(8, '0')}`,
+                `Previous block: ${hex(this.previous_offset)}`,
                 'Entries:',
             ].join('\n');
             for (const entry of this.items) {
                 if (!entry.offset)
                     continue;
-                text += `\n\t0x${entry.id.toString(16).padStart(8, '0')}: ${format(entry.size).padStart(5)} at 0x${entry.offset.toString(16).padStart(8, '0')}`;
+                text += `\n\t${hex(entry.id)}: ${format(entry.size).padStart(5)} at ${hex(entry.offset)}`;
             }
             return text;
         }
@@ -276,28 +274,26 @@ let MetadataBlock = (() => {
          */
         waitUnlocked(depth = 0) {
             if (depth > max_lock_attempts)
-                throw crit(withErrno('EBUSY', `sbfs: exceeded max attempts waiting for metadata block at ${this.offsetHex} to be unlocked`));
-            const i = this.length - 1;
-            if (!Atomics.load(this, i))
+                throw crit(withErrno('EBUSY', `sbfs: exceeded max attempts waiting for metadata block at ${hex(this.byteOffset)} to be unlocked`));
+            if (!Atomics.load(this, MetadataBlock.lockIndex))
                 return;
-            switch (Atomics.wait(this, i, 1)) {
+            switch (Atomics.wait(this, MetadataBlock.lockIndex, 1)) {
                 case 'ok':
                     break;
                 case 'not-equal':
                     depth++;
-                    err(`sbfs: waiting for metadata block at ${this.offsetHex} to be unlocked (${depth}/${max_lock_attempts})`);
+                    err(`sbfs: waiting for metadata block at ${hex(this.byteOffset)} to be unlocked (${depth}/${max_lock_attempts})`);
                     return this.waitUnlocked(depth);
                 case 'timed-out':
-                    throw crit(withErrno('EBUSY', `sbfs: timed out waiting for metadata block at ${this.offsetHex} to be unlocked`));
+                    throw crit(withErrno('EBUSY', `sbfs: timed out waiting for metadata block at ${hex(this.byteOffset)} to be unlocked`));
             }
         }
         lock() {
             this.waitUnlocked();
-            const i = offsetof(this, 'locked');
-            Atomics.store(this, i, 1);
+            Atomics.store(this, MetadataBlock.lockIndex, 1);
             const release = () => {
-                Atomics.store(this, i, 0);
-                Atomics.notify(this, i, 1);
+                Atomics.store(this, MetadataBlock.lockIndex, 0);
+                Atomics.notify(this, MetadataBlock.lockIndex, 1);
             };
             release[Symbol.dispose] = release;
             return release;
@@ -306,6 +302,9 @@ let MetadataBlock = (() => {
             super(...arguments);
             __runInitializers(this, _locked_extraInitializers);
         }
+        static {
+            __runInitializers(_classThis, _classExtraInitializers);
+        }
     };
     return MetadataBlock = _classThis;
 })();
@@ -425,7 +424,7 @@ let SuperBlock = (() => {
                 throw crit(withErrno('EIO', 'sbfs: checksum mismatch for super block'));
             this.metadata = new MetadataBlock(this.buffer, this.metadata_offset);
             if (this.metadata.checksum !== checksum(this.metadata))
-                throw crit(withErrno('EIO', `sbfs: checksum mismatch for metadata block (saved ${this.metadata.checksum.toString(16).padStart(8, '0')}, computed ${checksum(this.metadata).toString(16).padStart(8, '0')})`));
+                throw crit(withErrno('EIO', `sbfs: checksum mismatch for metadata block (saved ${hex(this.metadata.checksum)}, computed ${hex(checksum(this.metadata))})`));
             if (this.inode_format != _inode_version)
                 throw crit(withErrno('EIO', 'sbfs: inode format mismatch'));
             if (this.metadata_block_size != sizeof(MetadataBlock))
@@ -506,6 +505,7 @@ let SuperBlock = (() => {
             this.metadata_offset = metadata.byteOffset;
             _update(metadata);
             _update(this);
+            debug(`sbfs: rotated metadata block at ${hex(metadata.previous_offset)} with new block at ${hex(offset)}`);
             return metadata;
         }
         /**
@@ -541,7 +541,10 @@ export { SuperBlock };
  * Note we don't include the checksum when computing a new one.
  */
 function checksum(value) {
-    return crc32c(new Uint8Array(value.buffer, value.byteOffset + 4, sizeof(value) - 4));
+    let length = sizeof(value) - 4;
+    if (value instanceof MetadataBlock)
+        length -= Int32Array.BYTES_PER_ELEMENT;
+    return crc32c(new Uint8Array(value.buffer, value.byteOffset + 4, length));
 }
 /**
  * Update a block's checksum and timestamp.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zenfs/core",
-	"version": "2.4.2",
+	"version": "2.4.3",
 	"description": "A filesystem, anywhere",
 	"funding": {
 		"type": "individual",

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

@@ -1,8 +1,9 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
 import assert from 'node:assert';
+import { randomBytes } from 'node:crypto';
 import { suite, test } from 'node:test';
 import { Worker } from 'worker_threads';
-import { fs, mount, resolveMountConfig, SingleBuffer } from '@zenfs/core';
+import { fs, mount, resolveMountConfig, SingleBuffer, vfs } from '@zenfs/core';
 import { setupLogs } from '../logs.js';
 
 setupLogs();
@@ -51,4 +52,50 @@ await suite('SingleBuffer', () => {
 
 		assert(fs.existsSync('/shared/worker-file.ts'));
 	});
+
+	test('reliability across varied file sizes', async () => {
+		const mountPoint = '/sbfs-reliability';
+		const verifyMountPoint = '/sbfs-verify';
+		const buffer = new ArrayBuffer(0x400000);
+		const writable = await resolveMountConfig({ backend: SingleBuffer, buffer, label: 'reliability' });
+		mount(mountPoint, writable);
+
+		const filePath = `${mountPoint}/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) => {
+			mount(verifyMountPoint, writable);
+			try {
+				const reopened = fs.readFileSync(`${verifyMountPoint}/payload.bin`);
+				assert.strictEqual(reopened.byteLength, size, `snapshot size mismatch for ${size} bytes`);
+				assert.deepStrictEqual(reopened, expected, `snapshot content mismatch for ${size} bytes`);
+			} finally {
+				vfs.umount(verifyMountPoint);
+			}
+		};
+
+		try {
+			for (const size of growthSizes) {
+				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);
+			}
+
+			for (const size of 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 after shrink to ${size} bytes`);
+				assert.deepStrictEqual(direct, payload, `direct content mismatch after shrink to ${size} bytes`);
+				await verifySnapshot(direct, size);
+			}
+		} finally {
+			if (fs.existsSync(filePath)) fs.unlinkSync(filePath);
+			vfs.umount(mountPoint);
+		}
+	});
 });