@peerbit/native-backbone 0.2.8 → 0.2.9

package/dist/src/index.js

@@ -168,6 +168,19 @@ const nativeBackboneAppendProfileKeys = [
     "nativeBackboneRawReceiveGraphPutMs",
     "nativeBackboneRawReceiveCoordinateCommitMs",
 ];
+export class NativeBackboneCoordinatePersistenceReadLimitError extends Error {
+    file;
+    maxBytes;
+    observedBytes;
+    code = "ERR_NATIVE_BACKBONE_COORDINATE_READ_LIMIT";
+    constructor(file, maxBytes, observedBytes) {
+        super(`Native backbone coordinate persistence file ${file} exceeds the ${maxBytes} byte read limit (${observedBytes.toString()} bytes)`);
+        this.file = file;
+        this.maxBytes = maxBytes;
+        this.observedBytes = observedBytes;
+        this.name = "NativeBackboneCoordinatePersistenceReadLimitError";
+    }
+}
 const nativeBackboneCoordinatePersistenceFiles = {
     snapshot: "coordinates.bin",
     journal: "coordinates.wal",
@@ -280,6 +293,17 @@ const validateCoordinatePersistenceName = (name) => {
     }
     return name;
 };
+const validateCoordinatePersistenceReadMaxBytes = (maxBytes) => {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) {
+        throw new RangeError("Native backbone coordinate persistence read limit must be a non-negative safe integer");
+    }
+    return maxBytes;
+};
+const assertCoordinatePersistenceReadWithinLimit = (name, maxBytes, observedBytes) => {
+    if (BigInt(observedBytes) > BigInt(maxBytes)) {
+        throw new NativeBackboneCoordinatePersistenceReadLimitError(name, maxBytes, BigInt(observedBytes));
+    }
+};
 const nativeBackboneCoordinateDropTombstoneBodyBytes = (body) => new TextEncoder().encode(JSON.stringify(body));
 const nativeBackboneCoordinateDropChecksum = (bytes) => {
     let checksum = 0xffffffff;
@@ -2961,6 +2985,15 @@ export class NativeBackboneMemoryCoordinatePersistenceStore {
         const file = this.files.get(validateCoordinatePersistenceName(name));
         return file ? copyBytes(file) : undefined;
     }
+    async readLimited(name, maxBytes) {
+        const validName = validateCoordinatePersistenceName(name);
+        const limit = validateCoordinatePersistenceReadMaxBytes(maxBytes);
+        const file = this.files.get(validName);
+        if (file) {
+            assertCoordinatePersistenceReadWithinLimit(validName, limit, file.byteLength);
+        }
+        return file ? copyBytes(file) : undefined;
+    }
     async write(name, bytes) {
         this.files.set(validateCoordinatePersistenceName(name), copyBytes(bytes));
     }
@@ -2981,6 +3014,7 @@ export class NativeBackboneNodeCoordinatePersistenceStore {
     filePaths = new Map();
     directoryEnsured = false;
     appendFailure;
+    readLimited;
     durableBarrier;
     constructor(directory, fs) {
         this.directory = directory;
@@ -2991,6 +3025,9 @@ export class NativeBackboneNodeCoordinatePersistenceStore {
         if (!fs || typeof fs.open === "function") {
             this.durableBarrier = (name) => this.syncDurably(name);
         }
+        if (!fs || typeof fs.openBoundedRead === "function") {
+            this.readLimited = (name, maxBytes) => this.readWithinLimit(name, maxBytes);
+        }
     }
     async nodeFs() {
         return this.fs ?? (await importNodeFs());
@@ -3043,6 +3080,79 @@ export class NativeBackboneNodeCoordinatePersistenceStore {
             throw error;
         }
     }
+    async readWithinLimit(name, maxBytes) {
+        const validName = validateCoordinatePersistenceName(name);
+        const limit = validateCoordinatePersistenceReadMaxBytes(maxBytes);
+        const fs = await this.nodeFs();
+        const path = await this.filePath(validName);
+        let handle;
+        try {
+            if (this.fs) {
+                handle = await this.fs.openBoundedRead(path);
+            }
+            else {
+                if (!fs.open) {
+                    throw new Error("Default Node coordinate persistence does not expose FileHandle.open");
+                }
+                const opened = await fs.open(path, "r");
+                if (!opened.stat || !opened.read) {
+                    await opened.close();
+                    throw new Error("Default Node coordinate persistence bounded reads require FileHandle.stat and FileHandle.read");
+                }
+                handle = opened;
+            }
+        }
+        catch (error) {
+            if (isNotFoundError(error)) {
+                return undefined;
+            }
+            throw error;
+        }
+        try {
+            const initial = await handle.stat({ bigint: true });
+            if (typeof initial.size !== "bigint" || initial.size < 0n) {
+                throw new Error("Node coordinate persistence returned an invalid bigint file size");
+            }
+            assertCoordinatePersistenceReadWithinLimit(validName, limit, initial.size);
+            if (initial.size > BigInt(Number.MAX_SAFE_INTEGER)) {
+                throw new RangeError("Node coordinate persistence file is too large to materialize safely");
+            }
+            const byteLength = Number(initial.size);
+            const bytes = new Uint8Array(byteLength);
+            let offset = 0;
+            while (offset < byteLength) {
+                const { bytesRead } = await handle.read(bytes, offset, byteLength - offset, offset);
+                if (!Number.isSafeInteger(bytesRead) ||
+                    bytesRead <= 0 ||
+                    bytesRead > byteLength - offset) {
+                    throw new Error("Node coordinate persistence file changed during a bounded read");
+                }
+                offset += bytesRead;
+            }
+            const growthProbe = new Uint8Array(1);
+            const { bytesRead: growthBytes } = await handle.read(growthProbe, 0, 1, byteLength);
+            if (!Number.isSafeInteger(growthBytes) ||
+                growthBytes < 0 ||
+                growthBytes > 1) {
+                throw new Error("Node coordinate persistence returned invalid bounded read progress");
+            }
+            const final = await handle.stat({ bigint: true });
+            if (typeof final.size !== "bigint" || final.size < 0n) {
+                throw new Error("Node coordinate persistence returned an invalid bigint file size");
+            }
+            if (growthBytes !== 0 || final.size > initial.size) {
+                assertCoordinatePersistenceReadWithinLimit(validName, limit, final.size > initial.size ? final.size : initial.size + 1n);
+                throw new Error("Node coordinate persistence file changed during a bounded read");
+            }
+            if (final.size !== initial.size) {
+                throw new Error("Node coordinate persistence file changed during a bounded read");
+            }
+            return bytes;
+        }
+        finally {
+            await handle.close();
+        }
+    }
     async write(name, bytes) {
         const fs = await this.ensureDirectory();
         const path = await this.filePath(name);
@@ -3214,6 +3324,31 @@ export class NativeBackboneOPFSCoordinatePersistenceStore {
             throw error;
         }
     }
+    async readLimited(name, maxBytes) {
+        const validName = validateCoordinatePersistenceName(name);
+        const limit = validateCoordinatePersistenceReadMaxBytes(maxBytes);
+        try {
+            const handle = await this.directory.getFileHandle(validName, {
+                create: false,
+            });
+            const file = await handle.getFile();
+            if (!Number.isSafeInteger(file.size) || file.size < 0) {
+                throw new Error("OPFS coordinate persistence returned an invalid file size");
+            }
+            assertCoordinatePersistenceReadWithinLimit(validName, limit, file.size);
+            const buffer = await file.arrayBuffer();
+            if (buffer.byteLength !== file.size) {
+                throw new Error("OPFS coordinate persistence file changed during a bounded read");
+            }
+            return new Uint8Array(buffer);
+        }
+        catch (error) {
+            if (isNotFoundError(error)) {
+                return undefined;
+            }
+            throw error;
+        }
+    }
     async write(name, bytes) {
         const handle = await this.directory.getFileHandle(validateCoordinatePersistenceName(name), { create: true });
         const writable = await handle.createWritable();
@@ -3320,6 +3455,7 @@ export class NativeBackboneBufferedCoordinatePersistenceStore {
     options;
     buffers = new Map();
     bufferedBytes = 0;
+    readLimited;
     supportsRemoval;
     durableBarrier;
     constructor(inner, options = {}) {
@@ -3327,6 +3463,10 @@ export class NativeBackboneBufferedCoordinatePersistenceStore {
         this.options = options;
         this.supportsRemoval =
             inner.supportsRemoval ?? typeof inner.remove === "function";
+        if (typeof inner.readLimited === "function") {
+            const innerReadLimited = inner.readLimited.bind(inner);
+            this.readLimited = (name, maxBytes) => this.readWithinLimit(name, maxBytes, innerReadLimited);
+        }
         if (typeof inner.durableBarrier === "function") {
             this.durableBarrier = async (name) => {
                 await this.flush(name);
@@ -3347,6 +3487,44 @@ export class NativeBackboneBufferedCoordinatePersistenceStore {
         await this.flush(name);
         return this.inner.read(name);
     }
+    async readWithinLimit(name, maxBytes, innerReadLimited) {
+        const validName = validateCoordinatePersistenceName(name);
+        const limit = validateCoordinatePersistenceReadMaxBytes(maxBytes);
+        const pending = this.buffers.get(validName);
+        if (!pending || pending.length === 0) {
+            return innerReadLimited(validName, limit);
+        }
+        const pendingLength = pending.length;
+        let pendingBytes = 0n;
+        for (const chunk of pending) {
+            pendingBytes += BigInt(chunk.byteLength);
+        }
+        assertCoordinatePersistenceReadWithinLimit(validName, limit, pendingBytes);
+        const remaining = limit - Number(pendingBytes);
+        let existingBytes;
+        try {
+            existingBytes = (await innerReadLimited(validName, remaining))
+                ?.byteLength;
+        }
+        catch (error) {
+            if (error instanceof NativeBackboneCoordinatePersistenceReadLimitError) {
+                throw new NativeBackboneCoordinatePersistenceReadLimitError(validName, limit, pendingBytes + error.observedBytes);
+            }
+            throw error;
+        }
+        let confirmedPendingBytes = 0n;
+        for (const chunk of pending) {
+            confirmedPendingBytes += BigInt(chunk.byteLength);
+        }
+        if (this.buffers.get(validName) !== pending ||
+            pending.length !== pendingLength ||
+            confirmedPendingBytes !== pendingBytes) {
+            throw new Error("Native backbone coordinate persistence pending bytes changed during a bounded read");
+        }
+        assertCoordinatePersistenceReadWithinLimit(validName, limit, pendingBytes + BigInt(existingBytes ?? 0));
+        await this.flush(validName);
+        return innerReadLimited(validName, limit);
+    }
     async write(name, bytes) {
         await this.flush(name);
         await this.inner.write(name, bytes);