import { afterEach, describe, expect, it, vi } from "vitest"; import type { OpfsJournalPort, OpfsJournalTransaction, OpfsPreparedObject, OpfsPhysicalGenerationId, OpfsStorageScope, } from "../../src/application/ports/browser-file-storage/opfs-ports.ts"; import type { BrowserStoragePolicy, ByteSource, } from "../../src/application/ports/browser-file-storage/shared.ts"; import { browserDataFailure, browserDataSuccess, } from "../../src/adapters/browser-file-storage/result.ts"; import { createOpfsByteStoreAdapter } from "../../src/adapters/storage/opfs/opfs-byte-store-adapter.ts"; import { createIndexedDbOpfsJournal } from "../../src/adapters/storage/opfs/indexeddb-opfs-journal.ts"; import { resolveOpfsRuntimePolicy, } from "../../src/adapters/storage/opfs/opfs-policy.ts"; import { createOpfsWorkerGateway, type OpfsWorkerLike, } from "../../src/adapters/storage/opfs/opfs-worker-client.ts"; import { OPFS_WORKER_PROTOCOL_VERSION } from "../../src/adapters/storage/opfs/opfs-worker-protocol.ts"; import type { OpfsWorkerGateway, OpfsWorkerRequest, OpfsWorkerResponse, } from "../../src/adapters/storage/opfs/opfs-worker-protocol.ts"; import { createOpfsWorkerRuntime, startBrowserOpfsDedicatedWorker, type OpfsMutationLeaseManager, type OpfsWorkerMessageHost, type OpfsWorkerRuntime, } from "../../src/adapters/storage/opfs/opfs-worker-runtime.ts"; import { MemoryIndexedDbFactory } from "../helpers/memory-indexeddb.ts"; import { MemoryDirectory, MemoryFile, type MemoryNode, } from "../helpers/memory-opfs.ts"; const scopeA: OpfsStorageScope = Object.freeze({ namespace: "durable-objects", authorityToken: "authority_12345678", namespaceToken: "namespace_12345678", partitionToken: "partition_12345678", }); const scopeB: OpfsStorageScope = Object.freeze({ ...scopeA, authorityToken: "authority_87654321", }); const storagePolicy: BrowserStoragePolicy = Object.freeze({ owner: "test-owner", namespace: scopeA.namespace, classification: "PERSONAL", authority: "LOCAL_FIRST", accountScope: "OPAQUE_PARTITION", retention: Object.freeze({ kind: "EXPLICIT_DELETE" }), softBudgetBytes: 1024 * 1024, hardBudgetBytes: 2 * 1024 * 1024, evictionPriority: "USER_AUTHORED", logoutAction: "EXPORT_THEN_PURGE", accountDeletionAction: "PURGE_PARTITION", pressureAction: "RETAIN", unavailableFallback: "EXPORT_REQUIRED", }); const runtimePolicy = resolveOpfsRuntimePolicy({ chunkSizeBytes: 64 * 1024, maxObjectBytes: 64 * 1024, maxChunkCount: 1, orphanGracePeriodMs: 60_000, }); const PHYSICAL_GENERATION_A = "a".repeat(32) as OpfsPhysicalGenerationId; function beginRequest( requestId: string, transactionId: string, scope: OpfsStorageScope, physicalGenerationId: OpfsPhysicalGenerationId = PHYSICAL_GENERATION_A, ): OpfsWorkerRequest { return { requestId, protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "BEGIN_PUT", transactionId, scope, objectId: "object_12345678", generation: 1, physicalGenerationId, declaredByteLength: 1, mediaType: "application/octet-stream", createdAtEpochMs: 100, storagePolicy, chunkSizeBytes: runtimePolicy.chunkSizeBytes, }; } function immediateLeases(releases: { count: number }): OpfsMutationLeaseManager { return { async acquire() { let released = false; return { release() { if (released) return; released = true; releases.count += 1; }, }; }, }; } function expectFailureCode( response: OpfsWorkerResponse | null, code: string, ): void { expect(response).toMatchObject({ ok: false, failure: { code } }); } function preparedValue( response: OpfsWorkerResponse | null, ): OpfsPreparedObject { if ( !response?.ok || !("value" in response) || !response.value || typeof response.value !== "object" || response.value instanceof ArrayBuffer || !("descriptor" in response.value) ) { throw new Error("Expected a prepared OPFS object."); } return response.value; } describe("OPFS dedicated worker runtime", () => { it("cancels an exact BEGIN while waiting for a lock and releases a late lease", async () => { const root = new MemoryDirectory(); let resolveLease: | ((lease: { release(): void }) => void) | undefined; let acquireSignal: AbortSignal | undefined; let releases = 0; const leaseManager: OpfsMutationLeaseManager = { acquire(signal) { acquireSignal = signal; return new Promise((resolve) => { resolveLease = resolve; }); }, }; const runtime = createOpfsWorkerRuntime({ root: root as unknown as FileSystemDirectoryHandle, crypto: globalThis.crypto, policy: runtimePolicy, leaseManager, dedicatedWorker: true, supportsSynchronousAccessHandles: false, }); const beginning = runtime.handleRequest( beginRequest( "request_begin_1234", "transaction_12345678", scopeA, ), ); await Promise.resolve(); const aborted = await runtime.handleRequest({ requestId: "request_abort_1234", protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "ABORT_PUT", scope: scopeA, transactionId: "transaction_12345678", }); expect(aborted).toMatchObject({ ok: true }); expect(acquireSignal?.aborted).toBe(true); resolveLease?.({ release() { releases += 1; }, }); expectFailureCode(await beginning, "ABORTED"); expect(releases).toBe(1); expect(root.children.size).toBe(0); }); it("serializes APPEND against ABORT so no receipt or generation is resurrected", async () => { const root = new MemoryDirectory(); const releases = { count: 0 }; let resolveDigest: | ((digest: ArrayBuffer) => void) | undefined; const delayedCrypto = { subtle: { digest: () => new Promise((resolve) => { resolveDigest = resolve; }), }, } as unknown as Crypto; const runtime = createOpfsWorkerRuntime({ root: root as unknown as FileSystemDirectoryHandle, crypto: delayedCrypto, policy: runtimePolicy, leaseManager: immediateLeases(releases), dedicatedWorker: true, supportsSynchronousAccessHandles: false, }); expect( await runtime.handleRequest( beginRequest( "request_begin_5678", "transaction_56785678", scopeA, ), ), ).toMatchObject({ ok: true }); const appending = runtime.handleRequest({ requestId: "request_append_5678", protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "APPEND_CHUNK", scope: scopeA, transactionId: "transaction_56785678", sequence: 0, bytes: new Uint8Array([7]).buffer, }); await Promise.resolve(); const aborting = runtime.handleRequest({ requestId: "request_abort_5678", protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "ABORT_PUT", scope: scopeA, transactionId: "transaction_56785678", }); resolveDigest?.(new Uint8Array(32).buffer); expectFailureCode(await appending, "ABORTED"); expect(await aborting).toMatchObject({ ok: true }); expect(releases.count).toBe(1); expect( root.has([ "authorities", scopeA.authorityToken, scopeA.namespaceToken, scopeA.partitionToken, "staging", "transaction_56785678", ]), ).toBe(false); }); it("isolates physical chunks and cancellation tombstones by opaque authority", async () => { const root = new MemoryDirectory(); const releases = { count: 0 }; const runtime = createOpfsWorkerRuntime({ root: root as unknown as FileSystemDirectoryHandle, crypto: globalThis.crypto, policy: runtimePolicy, leaseManager: immediateLeases(releases), dedicatedWorker: true, supportsSynchronousAccessHandles: false, }); const transactionId = "transaction_99999999"; for (const [index, targetScope] of [scopeA, scopeB].entries()) { expect( await runtime.handleRequest( beginRequest( `request_begin_iso_${index}`, transactionId, targetScope, ), ), ).toMatchObject({ ok: true }); expect( await runtime.handleRequest({ requestId: `request_append_iso_${index}`, protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "APPEND_CHUNK", scope: targetScope, transactionId, sequence: 0, bytes: new Uint8Array([42]).buffer, }), ).toMatchObject({ ok: true }); } expect( await runtime.handleRequest({ requestId: "request_abort_iso_a", protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "ABORT_PUT", scope: scopeA, transactionId, }), ).toMatchObject({ ok: true }); const finished = await runtime.handleRequest({ requestId: "request_finish_iso_b", protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "FINISH_PUT", scope: scopeB, transactionId, }); expect(finished).toMatchObject({ ok: true }); const preparedObject = preparedValue(finished); expect( await runtime.handleRequest({ requestId: "request_verify_iso_b", protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "VERIFY_OBJECT", preparedObject, }), ).toEqual({ requestId: "request_verify_iso_b", protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: expect.any(String), ok: true, value: true, }); }); it("garbage-collects orphan chunks only inside the requested physical authority", async () => { const root = new MemoryDirectory(); const releases = { count: 0 }; const runtime = createOpfsWorkerRuntime({ root: root as unknown as FileSystemDirectoryHandle, crypto: globalThis.crypto, policy: runtimePolicy, leaseManager: immediateLeases(releases), dedicatedWorker: true, supportsSynchronousAccessHandles: false, }); const preparedByScope = new Map(); for (const [index, targetScope] of [scopeA, scopeB].entries()) { const transactionId = `transaction_gc_${index}_1234`; await runtime.handleRequest( beginRequest( `request_gc_begin_${index}`, transactionId, targetScope, ), ); await runtime.handleRequest({ requestId: `request_gc_append_${index}`, protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "APPEND_CHUNK", scope: targetScope, transactionId, sequence: 0, bytes: new Uint8Array([99]).buffer, }); const object = preparedValue( await runtime.handleRequest({ requestId: `request_gc_finish_${index}`, protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "FINISH_PUT", scope: targetScope, transactionId, }), ); preparedByScope.set(targetScope.authorityToken, object); await runtime.handleRequest({ requestId: `request_gc_finalize_${index}`, protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "FINALIZE_PUT", transactionId, preparedObject: object, }); } const digestHex = preparedByScope.get( scopeA.authorityToken, )!.chunks[0]!.digestHex; const cutoff = Date.now() + 10_000; expect( await runtime.handleRequest({ requestId: "request_gc_list_a", protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "LIST_ORPHAN_CANDIDATES", scope: scopeA, olderThanEpochMs: cutoff, maxEntries: 10, }), ).toMatchObject({ ok: true, value: { digests: [digestHex] } }); expect( await runtime.handleRequest({ requestId: "request_gc_delete_a", protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "DELETE_ORPHAN_CHUNK", scope: scopeA, digestHex, olderThanEpochMs: cutoff, }), ).toMatchObject({ ok: true, value: { deleted: true } }); expect( await runtime.handleRequest({ requestId: "request_gc_verify_a", protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "VERIFY_OBJECT", preparedObject: preparedByScope.get(scopeA.authorityToken)!, }), ).toEqual({ requestId: "request_gc_verify_a", protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: expect.any(String), ok: true, value: false, }); expect( await runtime.handleRequest({ requestId: "request_gc_verify_b", protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "VERIFY_OBJECT", preparedObject: preparedByScope.get(scopeB.authorityToken)!, }), ).toEqual({ requestId: "request_gc_verify_b", protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: expect.any(String), ok: true, value: true, }); }); it("reports every required capability and fails closed when the lock is absent", async () => { const runtime = createOpfsWorkerRuntime({ root: new MemoryDirectory() as unknown as FileSystemDirectoryHandle, crypto: globalThis.crypto, policy: runtimePolicy, leaseManager: null, dedicatedWorker: true, supportsSynchronousAccessHandles: true, }); expect( await runtime.handleRequest({ requestId: "request_caps_1234", protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "CAPABILITIES", }), ).toEqual({ requestId: "request_caps_1234", protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: expect.any(String), ok: true, value: { available: false, dedicatedWorkerRequired: true, crossContextMutationLockAvailable: false, synchronousAccessHandleAvailable: true, }, }); expectFailureCode( await runtime.handleRequest( beginRequest( "request_begin_caps", "transaction_caps_1234", scopeA, ), ), "UNSUPPORTED", ); }); }); function chunkFilePath( scope: OpfsStorageScope, digestHex: string, ): readonly string[] { return [ "authorities", scope.authorityToken, scope.namespaceToken, scope.partitionToken, "chunks", "sha256", digestHex.slice(0, 2), `${digestHex}.bin`, ]; } /** Seeds a chunk file whose lastModified (0) is far past any grace period. */ async function seedChunk( root: MemoryDirectory, scope: OpfsStorageScope, digestHex: string, ): Promise { const path = chunkFilePath(scope, digestHex); let directory = root as unknown as FileSystemDirectoryHandle; for (const segment of path.slice(0, -1)) { directory = await directory.getDirectoryHandle(segment, { create: true }); } await directory.getFileHandle(path.at(-1)!, { create: true }); } /** Wires the real client gateway to the real runtime through the protocol. */ function loopbackGateway( runtime: OpfsWorkerRuntime, policy = runtimePolicy, ): OpfsWorkerGateway { let listener: ((event: MessageEvent) => void) | undefined; let sequence = 0; return createOpfsWorkerGateway({ worker: { postMessage(message) { void runtime.handleRequest(message).then((response) => listener?.({ data: response } as MessageEvent), ); }, addEventListener(_type, next) { listener = next; }, removeEventListener() { listener = undefined; }, }, policy, createRequestId: () => `request_loopback_${++sequence}`, }); } /** A journal that only answers what reconciliation asks. */ function referenceJournal(referenced: ReadonlySet): OpfsJournalPort { const unused = async (): Promise => { throw new Error("Reconciliation does not use this journal method."); }; return { getCommittedObject: unused, begin: unused, markFilesReady: unused, commitPut: unused, commitDelete: unused, complete: unused, rollback: unused, listCommittedObjects: unused, countPartitionTransactions: unused, removePartition: unused, async listIncomplete() { return browserDataSuccess({ transactions: [], moreAvailable: false, corruptRows: 0, }); }, async isChunkReferenced(_scope, digestHex) { return browserDataSuccess(referenced.has(digestHex)); }, }; } describe("R-5.1 orphan GC pages past referenced chunks", () => { it("deletes orphans behind more than one batch of referenced chunks and keeps every referenced chunk", async () => { const root = new MemoryDirectory(); const runtime = createOpfsWorkerRuntime({ root: root as unknown as FileSystemDirectoryHandle, crypto: globalThis.crypto, policy: runtimePolicy, leaseManager: immediateLeases({ count: 0 }), dedicatedWorker: true, supportsSynchronousAccessHandles: false, }); // 150 referenced chunks, more than one orphanGcBatchSize (100). They are // written in descending digest order so directory order is not digest // order, and the two orphans sit at both ends of the digest range. const referenced = Array.from({ length: 150 }, (_, index) => (index + 1).toString(16).padStart(64, "0"), ).reverse(); const lowOrphan = "0".repeat(64); const highOrphan = "f".repeat(64); for (const digestHex of [...referenced, lowOrphan, highOrphan]) { await seedChunk(root, scopeA, digestHex); } const adapter = createOpfsByteStoreAdapter({ journal: referenceJournal(new Set(referenced)), worker: loopbackGateway(runtime), scope: scopeA, storagePolicy, policy: runtimePolicy, }); expect(await adapter.maintenance.reconcile()).toMatchObject({ ok: true, value: { inspectedOrphanChunks: 152, deletedOrphanChunks: 2, orphanGcStatus: "COMPLETED", }, }); expect(root.has(chunkFilePath(scopeA, lowOrphan))).toBe(false); expect(root.has(chunkFilePath(scopeA, highOrphan))).toBe(false); expect( referenced.filter( (digestHex) => !root.has(chunkFilePath(scopeA, digestHex)), ), ).toEqual([]); }); }); function memoryFileAt(root: MemoryDirectory, path: readonly string[]): MemoryFile { let current: MemoryNode = root; for (const segment of path) { if (!(current instanceof MemoryDirectory)) break; current = current.children.get(segment)!; } if (!(current instanceof MemoryFile)) throw new Error("No such file."); return current; } describe("R-5.2 a dedup-reused chunk is protected by the grace period again", () => { it("refreshes the chunk mtime on reuse so orphan GC neither lists nor deletes it", async () => { const root = new MemoryDirectory(); const runtime = createOpfsWorkerRuntime({ root: root as unknown as FileSystemDirectoryHandle, crypto: globalThis.crypto, policy: runtimePolicy, leaseManager: immediateLeases({ count: 0 }), dedicatedWorker: true, supportsSynchronousAccessHandles: false, }); async function putAndFinalize( transactionId: string, physicalGenerationId: OpfsPhysicalGenerationId, ): Promise { await runtime.handleRequest( beginRequest( `request_begin_${transactionId}`, transactionId, scopeA, physicalGenerationId, ), ); await runtime.handleRequest({ requestId: `request_append_${transactionId}`, protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "APPEND_CHUNK", scope: scopeA, transactionId, sequence: 0, bytes: new Uint8Array([77]).buffer, }); const prepared = preparedValue( await runtime.handleRequest({ requestId: `request_finish_${transactionId}`, protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "FINISH_PUT", scope: scopeA, transactionId, }), ); expect( await runtime.handleRequest({ requestId: `request_finalize_${transactionId}`, protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "FINALIZE_PUT", transactionId, preparedObject: prepared, }), ).toMatchObject({ ok: true }); return prepared; } const first = await putAndFinalize( "transaction_dedup_0001", PHYSICAL_GENERATION_A, ); const digestHex = first.chunks[0]!.digestHex; // The chunk is now older than any grace period. memoryFileAt(root, chunkFilePath(scopeA, digestHex)).lastModified = 0; const cutoff = Date.now() - runtimePolicy.orphanGracePeriodMs; expect( await runtime.handleRequest({ requestId: "request_dedup_list_before", protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "LIST_ORPHAN_CANDIDATES", scope: scopeA, olderThanEpochMs: cutoff, maxEntries: 10, }), ).toMatchObject({ ok: true, value: { digests: [digestHex] } }); // A second PUT of the same bytes reuses the chunk and then leaves staging, // so from here on only the chunk mtime protects it from a GC that read // "not referenced" just before the reuse committed. const second = await putAndFinalize( "transaction_dedup_0002", "b".repeat(32) as OpfsPhysicalGenerationId, ); expect(second.chunks[0]!.digestHex).toBe(digestHex); expect( await runtime.handleRequest({ requestId: "request_dedup_list_after", protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "LIST_ORPHAN_CANDIDATES", scope: scopeA, olderThanEpochMs: cutoff, maxEntries: 10, }), ).toMatchObject({ ok: true, value: { digests: [] } }); expect( await runtime.handleRequest({ requestId: "request_dedup_delete", protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "DELETE_ORPHAN_CHUNK", scope: scopeA, digestHex, olderThanEpochMs: cutoff, }), ).toMatchObject({ ok: true, value: { deleted: false } }); expect( await runtime.handleRequest({ requestId: "request_dedup_verify", protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "VERIFY_OBJECT", preparedObject: second, }), ).toMatchObject({ ok: true, value: true }); }); }); /** * One holder at a time, FIFO, and a queued request leaves the queue when its * signal aborts, the way a Web Lock request does. */ function exclusiveLeases(): OpfsMutationLeaseManager & { readonly waiting: number; readonly held: boolean; } { let held = false; const queue: Array<() => void> = []; const lease = () => { let released = false; return { release() { if (released) return; released = true; const next = queue.shift(); if (next) next(); else held = false; }, }; }; return { get waiting() { return queue.length; }, get held() { return held; }, acquire(signal) { if (signal?.aborted) { return Promise.reject(new DOMException("Aborted", "AbortError")); } if (!held) { held = true; return Promise.resolve(lease()); } return new Promise((resolve, reject) => { const grant = () => { signal?.removeEventListener("abort", onAbort); resolve(lease()); }; const onAbort = () => { queue.splice(queue.indexOf(grant), 1); reject(new DOMException("Aborted", "AbortError")); }; signal?.addEventListener("abort", onAbort, { once: true }); queue.push(grant); }); }, }; } /** A one-byte source that stalls until released, holding its put's lock. */ function stalledSource(): Readonly<{ source: ByteSource; streaming: Promise; release: () => void; }> { let markStreaming!: () => void; const streaming = new Promise((resolve) => { markStreaming = resolve; }); let release!: () => void; const gate = new Promise((resolve) => { release = resolve; }); return { source: { byteLength: 1, async *stream() { markStreaming(); await gate; yield browserDataSuccess(new Uint8Array([5])); }, }, streaming, release, }; } function bytesSource(bytes: Uint8Array): ByteSource { return { byteLength: bytes.byteLength, async *stream() { yield browserDataSuccess(Uint8Array.from(bytes)); }, }; } function oneByteSource(): ByteSource { return bytesSource(new Uint8Array([6])); } /** `suffix` is a hex digit so it also forms a physical generation id. */ function putRequest( suffix: string, source: ByteSource, ): Parameters[0] { return { transactionId: `transaction_put_${suffix}`, physicalGenerationId: suffix.padStart(32, "0") as OpfsPhysicalGenerationId, descriptor: { objectId: `object_put_${suffix}`, scope: scopeA, generation: 1, byteLength: source.byteLength!, mediaType: "application/octet-stream", createdAtEpochMs: 100, storagePolicy, }, source, }; } describe("R-5.3 lock waiting is not counted against the RPC timeout", () => { const lockPolicy = resolveOpfsRuntimePolicy({ ...runtimePolicy, rpcTimeoutMs: 60_000, mutationLockWaitTimeoutMs: 300_000, }); afterEach(() => { vi.useRealTimers(); }); /** * Put A holds the origin mutation lock while its source stalls. Put B's * BEGIN and a remove queue behind it, then the fake clock moves past * `advanceMs`. */ async function contendedLock(advanceMs: number) { const leases = exclusiveLeases(); const runtime = createOpfsWorkerRuntime({ root: new MemoryDirectory() as unknown as FileSystemDirectoryHandle, crypto: globalThis.crypto, policy: lockPolicy, leaseManager: leases, dedicatedWorker: true, supportsSynchronousAccessHandles: false, }); const gateway = loopbackGateway(runtime, lockPolicy); const stalled = stalledSource(); const putA = gateway.preparePut(putRequest("a", stalled.source)); await stalled.streaming; expect(leases.held).toBe(true); vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] }); const settled = new Set(); const putB = gateway.preparePut(putRequest("b", oneByteSource())); const removal = gateway.removeObject(scopeA, "object_lock_remove", 1); void putB.then(() => settled.add("putB")); void removal.then(() => settled.add("remove")); await vi.advanceTimersByTimeAsync(0); expect(leases.waiting).toBe(2); await vi.advanceTimersByTimeAsync(advanceMs); vi.useRealTimers(); return { leases, stalled, putA, putB, removal, settled }; } it("lets a put and a remove queued behind a long put run once the lock frees", async () => { const { leases, stalled, putA, putB, removal, settled } = await contendedLock(lockPolicy.rpcTimeoutMs + 1); expect(settled).toEqual(new Set()); expect(leases.waiting).toBe(2); stalled.release(); expect(await putA).toMatchObject({ ok: true }); expect(await putB).toMatchObject({ ok: true, value: { descriptor: { objectId: "object_put_b" } }, }); expect(await removal).toMatchObject({ ok: true }); expect(leases.held).toBe(false); }); it("ends a lock wait at the policy bound as a retryable BLOCKED", async () => { const { leases, stalled, putA, putB, removal } = await contendedLock( lockPolicy.mutationLockWaitTimeoutMs + 1, ); expect(await putB).toMatchObject({ ok: false, error: { code: "BLOCKED", retryable: true }, }); expect(await removal).toMatchObject({ ok: false, error: { code: "BLOCKED", retryable: true }, }); expect(leases.waiting).toBe(0); stalled.release(); expect(await putA).toMatchObject({ ok: true }); expect(leases.held).toBe(false); }); }); describe("R-5.5 stored objects are checked against their own chunk size", () => { const oldPolicy = resolveOpfsRuntimePolicy({ chunkSizeBytes: 64 * 1024, maxObjectBytes: 128 * 1024, maxChunkCount: 2, orphanGracePeriodMs: 60_000, }); const newPolicy = resolveOpfsRuntimePolicy({ chunkSizeBytes: 128 * 1024, maxObjectBytes: 128 * 1024, maxChunkCount: 1, orphanGracePeriodMs: 60_000, }); async function readAll(source: ByteSource): Promise { const bytes: number[] = []; for await (const chunk of source.stream(new AbortController().signal)) { if (!chunk.ok) throw new Error(chunk.error.code); bytes.push(...chunk.value); } return bytes; } it("reconciles and opens an object written before a chunk-size change and writes new objects at the new size", async () => { const root = new MemoryDirectory(); const runtimeFor = (policy: typeof oldPolicy) => createOpfsWorkerRuntime({ root: root as unknown as FileSystemDirectoryHandle, crypto: globalThis.crypto, policy, leaseManager: immediateLeases({ count: 0 }), dedicatedWorker: true, supportsSynchronousAccessHandles: false, }); const payload = Uint8Array.from( { length: 64 * 1024 + 1 }, (_, index) => index % 251, ); // Written with 64 KiB chunks and left FILES_READY, as a crash right // after FINISH_PUT would leave it. const before = loopbackGateway(runtimeFor(oldPolicy), oldPolicy); const written = await before.preparePut( putRequest("c", bytesSource(payload)), ); if (!written.ok) throw new Error(written.error.code); const stored = written.value; expect(stored.descriptor.integrity.chunkSizeBytes).toBe(64 * 1024); expect(stored.chunks).toHaveLength(2); // The chunk size is now 128 KiB. const after = loopbackGateway(runtimeFor(newPolicy), newPolicy); const transaction: OpfsJournalTransaction = { transactionId: "transaction_put_c", fencingToken: "fencing_12345678", mutation: "PUT", scope: scopeA, phase: "FILES_READY", objectId: stored.descriptor.objectId, expectedGeneration: null, targetGeneration: 1, targetByteLength: payload.byteLength, targetStoragePolicy: storagePolicy, budgetReservation: { namespace: scopeA.namespace, reservedBytes: payload.byteLength, hardBudgetBytes: storagePolicy.hardBudgetBytes, }, startedAtEpochMs: 100, preparedObject: stored, }; const rollback = vi.fn(async () => browserDataSuccess(undefined)); const adapter = createOpfsByteStoreAdapter({ journal: { ...referenceJournal( new Set(stored.chunks.map((chunk) => chunk.digestHex)), ), async listIncomplete() { return browserDataSuccess({ transactions: [transaction], moreAvailable: false, corruptRows: 0, }); }, async commitPut() { return browserDataSuccess({ ...transaction, phase: "COMMITTED" }); }, async complete() { return browserDataSuccess(undefined); }, rollback, }, worker: after, scope: scopeA, storagePolicy, policy: newPolicy, }); expect(await adapter.maintenance.reconcile()).toMatchObject({ ok: true, value: { committedTransactions: 1, rolledBackTransactions: 0 }, }); expect(rollback).not.toHaveBeenCalled(); const opened = await after.openObject(stored); if (!opened.ok) throw new Error(opened.error.code); expect(await readAll(opened.value)).toEqual([...payload]); // A new write still follows the current policy. const fresh = await after.preparePut(putRequest("d", bytesSource(payload))); expect(fresh).toMatchObject({ ok: true, value: { descriptor: { integrity: { chunkSizeBytes: 128 * 1024 } } }, }); expect(fresh.ok && fresh.value.chunks).toHaveLength(1); }); }); describe("Q-6.5-6 openObject checks the manifest up front and the bytes while streaming", () => { const twoChunkPolicy = resolveOpfsRuntimePolicy({ chunkSizeBytes: 64 * 1024, maxObjectBytes: 128 * 1024, maxChunkCount: 2, orphanGracePeriodMs: 60_000, }); const payload = Uint8Array.from( { length: 64 * 1024 + 1 }, (_, index) => index % 251, ); async function writeObject(bytes: Uint8Array) { const root = new MemoryDirectory(); const gateway = loopbackGateway( createOpfsWorkerRuntime({ root: root as unknown as FileSystemDirectoryHandle, crypto: globalThis.crypto, policy: twoChunkPolicy, leaseManager: immediateLeases({ count: 0 }), dedicatedWorker: true, supportsSynchronousAccessHandles: false, }), twoChunkPolicy, ); const written = await gateway.preparePut( putRequest("e", bytesSource(bytes)), ); if (!written.ok) throw new Error(written.error.code); return { root, gateway, stored: written.value }; } function filesNamed( directory: MemoryDirectory, matches: (name: string) => boolean, ): MemoryFile[] { const found: MemoryFile[] = []; for (const [name, node] of directory.children) { if (node instanceof MemoryDirectory) { found.push(...filesNamed(node, matches)); } else if (matches(name)) { found.push(node); } } return found; } function chunkFile(root: MemoryDirectory, digestHex: string): MemoryFile { const [file] = filesNamed(root, (name) => name === `${digestHex}.bin`); if (!file) throw new Error("Chunk file is missing."); return file; } /** Rewrites the root digest in both the stored manifest and the caller's copy. */ function withForgedRootDigest( root: MemoryDirectory, stored: OpfsPreparedObject, ): OpfsPreparedObject { const forged: OpfsPreparedObject = { ...stored, descriptor: { ...stored.descriptor, integrity: { ...stored.descriptor.integrity, rootDigestHex: "0".repeat(64), }, }, }; const [manifest] = filesNamed(root, (name) => name === "manifest.json"); if (!manifest) throw new Error("Manifest is missing."); manifest.bytes = new TextEncoder().encode(JSON.stringify(forged)); return forged; } async function drain(source: ByteSource) { const results: Array<{ ok: true; bytes: number } | { ok: false; code: string }> = []; for await (const chunk of source.stream(new AbortController().signal)) { results.push( chunk.ok ? { ok: true, bytes: chunk.value.byteLength } : { ok: false, code: chunk.error.code }, ); } return results; } it("opens without reading chunk bytes and reads each chunk once while streaming", async () => { const { root, gateway, stored } = await writeObject(payload); const chunks = stored.chunks.map((chunk) => chunkFile(root, chunk.digestHex), ); expect(chunks).toHaveLength(2); for (const file of chunks) file.reads = 0; const opened = await gateway.openObject(stored); if (!opened.ok) throw new Error(opened.error.code); expect(chunks.map((file) => file.reads)).toEqual([0, 0]); const bytes: number[] = []; for await (const chunk of opened.value.stream( new AbortController().signal, )) { if (!chunk.ok) throw new Error(chunk.error.code); bytes.push(...chunk.value); } expect(bytes).toEqual([...payload]); expect(chunks.map((file) => file.reads)).toEqual([1, 1]); }); it("still fails the read at a corrupted chunk", async () => { const { root, gateway, stored } = await writeObject(payload); const second = chunkFile(root, stored.chunks[1]!.digestHex); second.bytes = Uint8Array.from(second.bytes, (byte) => byte ^ 0xff); const opened = await gateway.openObject(stored); if (!opened.ok) throw new Error(opened.error.code); expect(await drain(opened.value)).toEqual([ { ok: true, bytes: 64 * 1024 }, { ok: false, code: "INTEGRITY_FAILED" }, ]); }); it("checks the root digest before the last chunk is released", async () => { const { root, gateway, stored } = await writeObject(payload); const forged = withForgedRootDigest(root, stored); const opened = await gateway.openObject(forged); if (!opened.ok) throw new Error(opened.error.code); expect(await drain(opened.value)).toEqual([ { ok: true, bytes: 64 * 1024 }, { ok: false, code: "INTEGRITY_FAILED" }, ]); }); it("checks the root digest of an empty object at open, where its stream ends", async () => { const { root, gateway, stored } = await writeObject(new Uint8Array()); expect(stored.chunks).toHaveLength(0); const intact = await gateway.openObject(stored); expect(intact.ok && (await drain(intact.value))).toEqual([]); const forged = withForgedRootDigest(root, stored); expect(await gateway.openObject(forged)).toMatchObject({ ok: false, error: { code: "INTEGRITY_FAILED" }, }); }); it("keeps verifyObject a full byte check", async () => { const { root, gateway, stored } = await writeObject(payload); const second = chunkFile(root, stored.chunks[1]!.digestHex); second.bytes = Uint8Array.from(second.bytes, (byte) => byte ^ 0xff); expect(await gateway.verifyObject(stored)).toEqual({ ok: true, value: false, }); }); }); describe("OPFS worker client lifecycle", () => { it("rejects a colliding concurrent request id without replacing the first RPC", async () => { let listener: ((event: MessageEvent) => void) | undefined; const posted: OpfsWorkerRequest[] = []; const worker: OpfsWorkerLike = { postMessage(message) { posted.push(message); }, addEventListener(_type, next) { listener = next; }, removeEventListener() { listener = undefined; }, }; const gateway = createOpfsWorkerGateway({ worker, policy: runtimePolicy, createRequestId: () => "request_collision_1234", }); const first = gateway.capabilities(); const second = gateway.capabilities(); expect(posted).toHaveLength(1); listener?.({ data: { requestId: "request_collision_1234", protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "CAPABILITIES", ok: true, value: { available: true, dedicatedWorkerRequired: true, crossContextMutationLockAvailable: true, synchronousAccessHandleAvailable: true, }, }, } as MessageEvent); const secondResult = await second; gateway.close(); await expect(first).resolves.toMatchObject({ ok: true }); expect(secondResult).toMatchObject({ ok: false, error: { code: "UNAVAILABLE" }, }); }); it("rejects pending RPCs immediately when the worker reports a fatal event", async () => { let failureListener: ((event: Event) => void) | undefined; const worker: OpfsWorkerLike = { postMessage() {}, addEventListener() {}, removeEventListener() {}, addFailureEventListener(listener) { failureListener = listener; }, removeFailureEventListener() { failureListener = undefined; }, }; const gateway = createOpfsWorkerGateway({ worker, policy: runtimePolicy, createRequestId: () => "request_crash_1234", }); const pending = gateway.capabilities(); expect(failureListener).toBeTypeOf("function"); if (!failureListener) { gateway.close(); return; } failureListener(new Event("error")); await expect(pending).resolves.toMatchObject({ ok: false, error: { code: "UNAVAILABLE" }, }); await expect(gateway.capabilities()).resolves.toMatchObject({ ok: false, error: { code: "UNAVAILABLE" }, }); }); it("scopes the open signal to verification and leaves the acquired source readable", async () => { let listener: | ((event: MessageEvent) => void) | undefined; const worker: OpfsWorkerLike = { postMessage(message) { const response: OpfsWorkerResponse = message.kind === "VERIFY_OBJECT" ? { requestId: message.requestId, protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: message.kind, ok: true, value: true, } : { requestId: message.requestId, protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: message.kind, ok: true, value: new Uint8Array([4, 2]).buffer, }; queueMicrotask(() => listener?.({ data: response } as MessageEvent), ); }, addEventListener(_type, nextListener) { listener = nextListener; }, removeEventListener() { listener = undefined; }, }; let requestSequence = 0; const gateway = createOpfsWorkerGateway({ worker, policy: runtimePolicy, createRequestId: () => `request_open_${++requestSequence}_1234`, }); const preparedObject: OpfsPreparedObject = { physicalSchemaVersion: 1, descriptor: { objectId: "object_open_12345678", scope: scopeA, generation: 1, byteLength: 2, mediaType: "application/octet-stream", createdAtEpochMs: 100, integrity: { algorithm: "SHA-256-TREE-V1", rootDigestHex: "a".repeat(64), chunkSizeBytes: runtimePolicy.chunkSizeBytes, }, storagePolicy, }, chunks: [ { sequence: 0, byteLength: 2, digestHex: "b".repeat(64), }, ], }; const openController = new AbortController(); const opened = await gateway.openObject( preparedObject, openController.signal, ); expect(opened.ok).toBe(true); openController.abort(); const chunks: number[][] = []; if (opened.ok) { for await (const result of opened.value.stream( new AbortController().signal, )) { expect(result.ok).toBe(true); if (result.ok) chunks.push([...result.value]); } } expect(chunks).toEqual([[4, 2]]); gateway.close(); }); it("removes its listener and rejects all pending RPCs before Worker termination", async () => { const listeners = new Set<(event: MessageEvent) => void>(); const worker: OpfsWorkerLike = { postMessage() {}, addEventListener(_type, listener) { listeners.add(listener); }, removeEventListener(_type, listener) { listeners.delete(listener); }, }; const gateway = createOpfsWorkerGateway({ worker, policy: runtimePolicy, createRequestId: () => "request_pending_1234", }); const pending = gateway.capabilities(); expect(listeners.size).toBe(1); gateway.close(); expect(listeners.size).toBe(0); await expect(pending).resolves.toMatchObject({ ok: false, error: { code: "UNAVAILABLE" }, }); await expect(gateway.capabilities()).resolves.toMatchObject({ ok: false, error: { code: "UNAVAILABLE" }, }); }); }); /** * STO-RR-01. A Web Lock is not reentrant. Any path that re-acquires the origin * mutation lease while already holding it stops making progress forever, and a * lock the runtime waits on cannot be observed by a fake that hands out an * unlimited number of leases. */ function strictNonReentrantLeases( counters: { acquires: number; releases: number }, ): OpfsMutationLeaseManager { let held = false; return { async acquire() { if (held) { // A second holder waits for the first to release. Nothing here ever // does, which is exactly what a deadlock looks like. return await new Promise(() => {}); } held = true; counters.acquires += 1; let released = false; return { release() { if (released) return; released = true; held = false; counters.releases += 1; }, }; }, }; } function withTimeout( operation: Promise, label: string, ms = 200, ): Promise { return Promise.race([ operation, new Promise((_resolve, reject) => { setTimeout(() => reject(new Error(`${label} did not settle`)), ms); }), ]); } describe("STO-RR-01 OPFS finalization under a non-reentrant lock", () => { async function completedPut( runtime: ReturnType, transactionId: string, ): Promise { expect( await runtime.handleRequest( beginRequest(`request_begin_${transactionId}`, transactionId, scopeA), ), ).toMatchObject({ ok: true }); expect( await runtime.handleRequest({ requestId: `request_append_${transactionId}`, protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "APPEND_CHUNK", scope: scopeA, transactionId, sequence: 0, bytes: new Uint8Array([9]).buffer, }), ).toMatchObject({ ok: true }); const finished = await runtime.handleRequest({ requestId: `request_finish_${transactionId}`, protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "FINISH_PUT", scope: scopeA, transactionId, }); expect(finished).toMatchObject({ ok: true }); return preparedValue(finished); } it("finalizes a normal PUT with exactly one lock acquisition", async () => { const root = new MemoryDirectory(); const counters = { acquires: 0, releases: 0 }; const runtime = createOpfsWorkerRuntime({ root: root as unknown as FileSystemDirectoryHandle, crypto: globalThis.crypto, policy: runtimePolicy, leaseManager: strictNonReentrantLeases(counters), dedicatedWorker: true, supportsSynchronousAccessHandles: false, }); const transactionId = "transaction_final_0001"; const prepared = await completedPut(runtime, transactionId); const before = counters.acquires; const finalized = await withTimeout( runtime.handleRequest({ requestId: "request_finalize_0001", protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "FINALIZE_PUT", transactionId, preparedObject: prepared, }), "FINALIZE_PUT", ); expect(finalized).toMatchObject({ ok: true }); expect(counters.acquires - before).toBe(1); expect(counters.acquires).toBe(counters.releases); expect( root.has([ "authorities", scopeA.authorityToken, scopeA.namespaceToken, scopeA.partitionToken, "staging", transactionId, ]), ).toBe(false); }); it("leaves the lock free for the next mutation after a finalized PUT", async () => { const root = new MemoryDirectory(); const counters = { acquires: 0, releases: 0 }; const runtime = createOpfsWorkerRuntime({ root: root as unknown as FileSystemDirectoryHandle, crypto: globalThis.crypto, policy: runtimePolicy, leaseManager: strictNonReentrantLeases(counters), dedicatedWorker: true, supportsSynchronousAccessHandles: false, }); const first = "transaction_final_0002"; const prepared = await completedPut(runtime, first); await withTimeout( runtime.handleRequest({ requestId: "request_finalize_0002", protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "FINALIZE_PUT", transactionId: first, preparedObject: prepared, }), "first FINALIZE_PUT", ); const second = "transaction_final_0003"; await expect( withTimeout(completedPut(runtime, second), "second PUT"), ).resolves.toMatchObject({ descriptor: { objectId: "object_12345678" } }); expect(counters.acquires).toBe(counters.releases); }); }); /** * STO-RR-02. A failure raised while serving a validated request must answer * that request. Defaulting the response kind to `CAPABILITIES` made the client's * own expected-kind check reject it as a protocol breach, so a quota or * integrity failure reached the caller as `UNSUPPORTED`. */ describe("STO-RR-02 worker failure responses echo the request kind", () => { const failingRoot = { async getDirectoryHandle(): Promise { throw new DOMException("Out of room", "QuotaExceededError"); }, async getFileHandle(): Promise { throw new DOMException("Out of room", "QuotaExceededError"); }, async removeEntry(): Promise { throw new DOMException("Out of room", "QuotaExceededError"); }, async *entries(): AsyncIterableIterator {}, } as unknown as FileSystemDirectoryHandle; it("keeps the validated kind on every failure path", async () => { const counters = { acquires: 0, releases: 0 }; const runtime = createOpfsWorkerRuntime({ root: failingRoot, crypto: globalThis.crypto, policy: runtimePolicy, leaseManager: strictNonReentrantLeases(counters), dedicatedWorker: true, supportsSynchronousAccessHandles: false, }); const requests: readonly OpfsWorkerRequest[] = [ beginRequest("request_kind_begin", "transaction_kind_0001", scopeA), { requestId: "request_kind_remove", protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "REMOVE_OBJECT", scope: scopeA, objectId: "object_12345678", generation: 1, }, { requestId: "request_kind_cleanup", protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "CLEANUP_TRANSACTION", scope: scopeA, transactionId: "transaction_kind_0001", }, { requestId: "request_kind_orphans", protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "LIST_ORPHAN_CANDIDATES", scope: scopeA, olderThanEpochMs: 1, maxEntries: 1, }, ]; for (const request of requests) { const response = await runtime.handleRequest(request); expect(response).toMatchObject({ ok: false, kind: request.kind, requestId: request.requestId, protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, }); } }); it("still reports a protocol-level failure for an unreadable envelope", async () => { const counters = { acquires: 0, releases: 0 }; const runtime = createOpfsWorkerRuntime({ root: failingRoot, crypto: globalThis.crypto, policy: runtimePolicy, leaseManager: strictNonReentrantLeases(counters), dedicatedWorker: true, supportsSynchronousAccessHandles: false, }); expect( await runtime.handleRequest({ requestId: "request_kind_broken", protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "NOT_A_KIND", }), ).toMatchObject({ ok: false, kind: "CAPABILITIES" }); }); }); /** * STO-RR-03. The client decoder is the trust boundary for anything a worker * says. A `code` that is merely a string lets an arbitrary value escape the * closed `BrowserDataFailure` taxonomy into application code. */ describe("STO-RR-03 worker responses are decoded against closed sets", () => { function respondingWorker( reply: (request: OpfsWorkerRequest) => unknown, ): OpfsWorkerLike { const listeners = new Set<(event: MessageEvent) => void>(); return { postMessage(message: unknown) { const response = reply(message as OpfsWorkerRequest); queueMicrotask(() => { for (const listener of listeners) { listener({ data: response } as MessageEvent); } }); }, addEventListener(_type: "message", listener: (event: MessageEvent) => void) { listeners.add(listener); }, removeEventListener(_type: "message", listener: (event: MessageEvent) => void) { listeners.delete(listener); }, } as unknown as OpfsWorkerLike; } const hostileReplies: readonly (readonly [string, (request: OpfsWorkerRequest) => unknown])[] = [ [ "unknown failure code", (request) => ({ requestId: request.requestId, protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: request.kind, ok: false, failure: { code: "EVIL", retryable: false }, }), ], [ "unknown request kind", (request) => ({ requestId: request.requestId, protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "NOT_A_KIND", ok: false, failure: { code: "UNAVAILABLE", retryable: false }, }), ], [ "non-boolean retryable", (request) => ({ requestId: request.requestId, protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: request.kind, ok: false, failure: { code: "UNAVAILABLE", retryable: "yes" }, }), ], [ "inherited failure fields", (request) => ({ requestId: request.requestId, protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: request.kind, ok: false, failure: Object.create({ code: "UNAVAILABLE", retryable: false }) as object, }), ], [ "throwing getter", (request) => { const response: Record = { requestId: request.requestId, protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, ok: false, failure: { code: "UNAVAILABLE", retryable: false }, }; Object.defineProperty(response, "kind", { enumerable: true, get: () => { throw new TypeError("hostile getter"); }, }); return response; }, ], [ "extra own field", (request) => ({ requestId: request.requestId, protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: request.kind, ok: false, failure: { code: "UNAVAILABLE", retryable: false, injected: 1 }, }), ], ]; for (const [label, reply] of hostileReplies) { it(`closes a ${label} as UNSUPPORTED without rejecting`, async () => { const gateway = createOpfsWorkerGateway({ worker: respondingWorker(reply), policy: runtimePolicy, createRequestId: () => `request_hostile_${label.replace(/\W/gu, "")}`, }); const result = await withTimeout(gateway.capabilities(), label); expect(result.ok).toBe(false); expect(result.ok ? null : result.error.code).toBe("UNSUPPORTED"); }); } /** * NS-06. Correlation was read separately and the pending row and its timer * were removed before the reply was decoded. A trap that threw inside the * decoder therefore left the public promise pending forever, and a throwing * `requestId` getter produced a timeout instead of a prompt protocol failure. */ const uncorrelatableReplies: readonly (readonly [ string, (request: OpfsWorkerRequest) => unknown, ])[] = [ [ "throwing requestId getter", (request) => Object.defineProperty( { protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: request.kind, ok: true, value: {}, }, "requestId", { enumerable: true, get: () => { throw new TypeError("hostile requestId getter"); }, }, ), ], [ "throwing ownKeys trap", (request) => new Proxy( { requestId: request.requestId, protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: request.kind, ok: true, value: {}, }, { ownKeys() { throw new TypeError("hostile ownKeys trap"); }, }, ), ], [ "descriptor trap that throws after correlation", (request) => { let reads = 0; return new Proxy( { requestId: request.requestId, protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: request.kind, ok: true, value: {}, }, { getOwnPropertyDescriptor(target, key) { reads += 1; if (reads > 1) { throw new TypeError("stateful descriptor trap"); } return Reflect.getOwnPropertyDescriptor(target, key); }, }, ); }, ], [ "symbol-keyed field", (request) => ({ requestId: request.requestId, protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: request.kind, ok: true, value: {}, [Symbol.for("injected")]: true, }), ], [ "non-enumerable own field", (request) => Object.defineProperty( { requestId: request.requestId, protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: request.kind, ok: true, value: {}, }, "injected", { enumerable: false, value: true }, ), ], ]; for (const [label, reply] of uncorrelatableReplies) { it(`closes a ${label} promptly as UNSUPPORTED`, async () => { const gateway = createOpfsWorkerGateway({ worker: respondingWorker(reply), policy: { ...runtimePolicy, rpcTimeoutMs: 60_000 }, createRequestId: () => `request_uncorr_${label.replace(/\W/gu, "")}`, }); // The RPC timeout is far beyond the test budget, so a pass here means the // reply itself closed the request rather than the timer. const result = await withTimeout(gateway.capabilities(), label); expect(result.ok).toBe(false); expect(result.ok ? null : result.error.code).toBe("UNSUPPORTED"); }); } it("keeps serving requests after a malformed reply", async () => { let replies = 0; const gateway = createOpfsWorkerGateway({ worker: respondingWorker((request) => { replies += 1; if (replies === 1) return { requestId: request.requestId }; return { requestId: request.requestId, protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: request.kind, ok: false, failure: { code: "QUOTA_EXCEEDED", retryable: true }, }; }), policy: { ...runtimePolicy, rpcTimeoutMs: 60_000 }, createRequestId: () => `request_sequence_${replies}`, }); const first = await withTimeout(gateway.capabilities(), "first"); expect(first.ok ? null : first.error.code).toBe("UNSUPPORTED"); const second = await withTimeout(gateway.capabilities(), "second"); expect(second.ok ? null : second.error.code).toBe("QUOTA_EXCEEDED"); }); it("still admits a well-formed closed failure", async () => { const gateway = createOpfsWorkerGateway({ worker: respondingWorker((request) => ({ requestId: request.requestId, protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: request.kind, ok: false, failure: { code: "QUOTA_EXCEEDED", retryable: true }, })), policy: runtimePolicy, createRequestId: () => "request_wellformed_1234", }); const result = await withTimeout(gateway.capabilities(), "well-formed"); expect(result.ok).toBe(false); expect(result.ok ? null : result.error.code).toBe("QUOTA_EXCEEDED"); }); }); /** * NS-05. When the runtime never came up, the message host answered with a * default `CAPABILITIES` kind. The gateway saw that as an expected-kind * mismatch and replaced the real cause — `BLOCKED`, `QUOTA_EXCEEDED` — with a * generic `UNSUPPORTED` protocol breach, so the outage was misreported. */ describe("NS-05 a bootstrap failure answers the request it belongs to", () => { function hostFor(): Readonly<{ host: OpfsWorkerMessageHost; posted: OpfsWorkerResponse[]; deliver(message: unknown): void; }> { const listeners: ((event: MessageEvent) => void)[] = []; const posted: OpfsWorkerResponse[] = []; return { host: { addEventListener(_type, listener) { listeners.push(listener); }, postMessage(message) { posted.push(message); }, }, posted, deliver(message: unknown) { for (const listener of listeners) { listener({ data: message } as MessageEvent); } }, }; } const requestKinds = [ "CAPABILITIES", "BEGIN_PUT", "APPEND_CHUNK", "FINISH_PUT", "ABORT_PUT", "VERIFY_OBJECT", "READ_CHUNK", "REMOVE_OBJECT", "CLEANUP_TRANSACTION", "FINALIZE_PUT", "LIST_ORPHAN_CANDIDATES", "DELETE_ORPHAN_CHUNK", ] as const; for (const kind of requestKinds) { it(`preserves the ${kind} correlation when bootstrap fails`, async () => { const { host, posted, deliver } = hostFor(); const start = startBrowserOpfsDedicatedWorker(host, { storageManager: { getDirectory: () => Promise.reject( new DOMException("blocked", "SecurityError"), ), } as unknown as StorageManager, crypto: globalThis.crypto, }); // The bootstrap rejection must not escape the worker entry point either. await expect(start).rejects.toBeInstanceOf(Error); deliver({ requestId: "request_bootstrap_failure", protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind, }); await new Promise((resolve) => setTimeout(resolve, 0)); expect(posted).toHaveLength(1); expect(posted[0]).toMatchObject({ requestId: "request_bootstrap_failure", protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind, ok: false, }); }); } }); /** * Two runtimes ("tabs") share one OPFS root, one exclusive worker lock and * one journal database, the way two tabs of one origin do. */ function sharedRootTabs(policy = runtimePolicy) { const root = new MemoryDirectory(); const leases = exclusiveLeases(); const idb = new MemoryIndexedDbFactory(); const tab = ( tag: string, extra: Partial[0]> = {}, ) => { const tabScope = extra.scope ?? scopeA; const runtime = createOpfsWorkerRuntime({ root: root as unknown as FileSystemDirectoryHandle, crypto: globalThis.crypto, policy, leaseManager: leases, dedicatedWorker: true, supportsSynchronousAccessHandles: false, }); let sequence = 0; return createOpfsByteStoreAdapter({ journal: createIndexedDbOpfsJournal({ authorityToken: tabScope.authorityToken, factory: idb.factory, keyRange: idb.keyRange, }), worker: loopbackGateway(runtime, policy), scope: tabScope, storagePolicy, policy, createTransactionId: () => `transaction_${tag}_${++sequence}`, ...extra, }); }; return { root, leases, idb, tab }; } async function openedBytes( adapter: ReturnType, objectId: string, ): Promise | string> { const opened = await adapter.objects.open({ objectId }); if (!opened.ok) return opened.error.code; const bytes: number[] = []; for await (const chunk of opened.value.source.stream( new AbortController().signal, )) { if (!chunk.ok) return chunk.error.code; bytes.push(...chunk.value); } return { generation: opened.value.descriptor.generation, bytes }; } describe("05-01 reconcile leaves a live put's journal row alone", () => { it.each([ ["a first put", null], ["an overwrite", 1], ] as const)( "keeps %s that reconcile overlapped in another tab", async (_label, expectedGeneration) => { const { tab } = sharedRootTabs(); const tabA = tab("a"); const tabB = tab("b"); if (expectedGeneration !== null) { expect( await tabA.objects.put({ objectId: "object_12345678", expectedGeneration: null, mediaType: "application/octet-stream", source: oneByteSource(), }), ).toMatchObject({ ok: true, value: { generation: 1 } }); } const stalled = stalledSource(); const putA = tabA.objects.put({ objectId: "object_12345678", expectedGeneration, mediaType: "application/octet-stream", source: stalled.source, }); // Tab A holds the worker lock and its journal row is PREPARING. await stalled.streaming; const reconcileB = tabB.maintenance.reconcile(); await new Promise((resolve) => setTimeout(resolve, 20)); stalled.release(); const [put, reconciled] = await Promise.all([putA, reconcileB]); const generation = (expectedGeneration ?? 0) + 1; expect(put).toMatchObject({ ok: true, value: { generation } }); expect(reconciled).toMatchObject({ ok: true, value: { skippedLiveTransactions: 1, rolledBackTransactions: 0 }, }); expect(await openedBytes(tabA, "object_12345678")).toEqual({ generation, bytes: [5], }); }, ); }); describe("05-02 an empty receipt left by a failed first write is no receipt", () => { it("cleans a crash-left empty receipt and keeps orphan GC sweeping", async () => { const root = new MemoryDirectory(); const runtime = createOpfsWorkerRuntime({ root: root as unknown as FileSystemDirectoryHandle, crypto: globalThis.crypto, policy: runtimePolicy, leaseManager: immediateLeases({ count: 0 }), dedicatedWorker: true, supportsSynchronousAccessHandles: false, }); // `getFileHandle({create:true})` made the file; the write never landed. let directory = root as unknown as FileSystemDirectoryHandle; for (const segment of [ "authorities", scopeA.authorityToken, scopeA.namespaceToken, scopeA.partitionToken, "staging", "transaction_empty_0001", ]) { directory = await directory.getDirectoryHandle(segment, { create: true }); } await directory.getFileHandle("receipt.json", { create: true }); const orphan = "0".repeat(64); await seedChunk(root, scopeA, orphan); expect( await runtime.handleRequest({ requestId: "request_empty_list", protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "LIST_ORPHAN_CANDIDATES", scope: scopeA, olderThanEpochMs: Date.now(), maxEntries: 10, }), ).toMatchObject({ ok: true, value: { safeToSweep: true, digests: [orphan] }, }); expect( await runtime.handleRequest({ requestId: "request_empty_cleanup", protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "CLEANUP_TRANSACTION", scope: scopeA, transactionId: "transaction_empty_0001", }), ).toMatchObject({ ok: true, value: { kind: "ALREADY_CLEAN" } }); expect( root.has([ "authorities", scopeA.authorityToken, scopeA.namespaceToken, scopeA.partitionToken, "staging", "transaction_empty_0001", ]), ).toBe(false); }); it("compensates a put whose first receipt write hit the quota, so reconcile runs and the same id retries", async () => { const { tab } = sharedRootTabs(); const store = tab("q"); const getFileHandle = MemoryDirectory.prototype.getFileHandle; let failReceipt = true; vi.spyOn(MemoryDirectory.prototype, "getFileHandle").mockImplementation( async function (this: MemoryDirectory, name, options) { const handle = await getFileHandle.call(this, name, options); if (name !== "receipt.json" || !failReceipt) return handle; failReceipt = false; return { ...handle, async createWritable() { const writable = await handle.createWritable(); return { write: (data: FileSystemWriteChunkType) => writable.write(data), abort: () => writable.abort(), async close() { throw new DOMException("Quota exceeded.", "QuotaExceededError"); }, } as unknown as FileSystemWritableFileStream; }, } as FileSystemFileHandle; }, ); const put = () => store.objects.put({ objectId: "object_12345678", expectedGeneration: null, mediaType: "application/octet-stream", source: oneByteSource(), }); const failed = await put(); expect(failed).toMatchObject({ ok: false, error: { code: "QUOTA_EXCEEDED" }, }); expect(failed.ok || failed.error.recovery).not.toBe("RECONCILE"); expect(await store.maintenance.reconcile()).toMatchObject({ ok: true, value: { inspectedTransactions: 0, orphanGcStatus: "COMPLETED" }, }); expect(await put()).toMatchObject({ ok: true, value: { generation: 1 } }); }); }); describe("05-04 a LOGOUT or ACCOUNT_DELETION purge leaves no partition bytes behind", () => { const scopeP2: OpfsStorageScope = Object.freeze({ ...scopeA, partitionToken: "partition_87654321", }); const authority = { requestMaintenanceAuthority: () => ({ authorized: true as const, proofToken: "proof_token_1234567890", expiresAtEpochMs: Date.now() + 60_000, }), consumeMaintenanceAuthority: () => true, }; function filesUnder(root: MemoryDirectory, scope: OpfsStorageScope): string[] { const files: string[] = []; const walk = (directory: MemoryDirectory, path: string) => { for (const [name, node] of directory.children) { if (node instanceof MemoryDirectory) walk(node, `${path}/${name}`); else files.push(`${path}/${name}`); } }; const partition = [ "authorities", scope.authorityToken, scope.namespaceToken, scope.partitionToken, ].reduce( (node, segment) => node instanceof MemoryDirectory ? node.children.get(segment) : node, root, ); if (partition instanceof MemoryDirectory) walk(partition, ""); return files; } const putBytes = ( adapter: ReturnType, objectId: string, bytes: number[], ) => adapter.objects.put({ objectId, expectedGeneration: null, mediaType: "application/octet-stream", source: bytesSource(new Uint8Array(bytes)), }); it.each(["LOGOUT", "ACCOUNT_DELETION"] as const)( "removes the chunks of a %s-purged partition and keeps other partitions", async (reason) => { const { root, tab } = sharedRootTabs(); const purged = tab("p", authority); const kept = tab("k", { ...authority, scope: scopeP2 }); expect(await putBytes(purged, "object_secret_1", [1, 2, 3])).toMatchObject({ ok: true }); expect(await putBytes(purged, "object_secret_2", [4, 5])).toMatchObject({ ok: true }); expect(await putBytes(kept, "object_kept_0001", [7, 7])).toMatchObject({ ok: true }); const report = await purged.maintenance.enforcePolicies({ reason }); expect(report).toMatchObject({ ok: true, value: { removedObjects: 2, moreObjectsAvailable: false, deadlineReached: false, partitionDeleted: true, }, }); expect(report.ok && report.value.chunkSweep).toBeUndefined(); expect(filesUnder(root, scopeA)).toEqual([]); expect(await openedBytes(kept, "object_kept_0001")).toEqual({ generation: 1, bytes: [7, 7], }); }, ); // 1101/13.6. A journal may hand back a page shorter than the limit (the port // does not promise full pages). A purge that walked two such pages and // removed everything is finished: it must say so and take the partition. it("finishes a purge that walked more than one journal page", async () => { const { root, idb, tab } = sharedRootTabs(); const journal = createIndexedDbOpfsJournal({ authorityToken: scopeA.authorityToken, factory: idb.factory, keyRange: idb.keyRange, }); const purged = tab("p", { ...authority, journal: { ...journal, listCommittedObjects: (request) => journal.listCommittedObjects({ ...request, limit: 1 }), }, }); expect(await putBytes(purged, "object_secret_1", [1, 2, 3])).toMatchObject({ ok: true }); expect(await putBytes(purged, "object_secret_2", [4, 5])).toMatchObject({ ok: true }); expect( await purged.maintenance.enforcePolicies({ reason: "ACCOUNT_DELETION" }), ).toMatchObject({ ok: true, value: { inspectedObjects: 2, removedObjects: 2, moreObjectsAvailable: false, partitionDeleted: true, }, }); expect(filesUnder(root, scopeA)).toEqual([]); }); // 2026-11-03 05-01 X1. The purge used to walk past a put that began before // it, report a completed sweep and leave that object readable. A put or // delete of the partition that has not finished now sends the purge to the // partition delete, which waits for it and then takes it. // 1103/05-01 rest (Y1b). That fix counted the journal once, after the walk. // Each remove waits for the origin lease the other tab's put holds, so with // three or more objects the put committed and settled before the count: // neither the listing nor the count saw it, the sweep skipped its chunks // and said COMPLETED, and the file stayed readable. One object hid this. it.each([1, 3, 8])( "waits for a put that began before the purge and takes it with the partition (%i committed objects)", async (count) => { const { root, tab } = sharedRootTabs(); const purger = tab("p", authority); const writer = tab("w", authority); for (let index = 1; index <= count; index += 1) { expect( await putBytes(purger, `object_secret_${index}`, [index]), ).toMatchObject({ ok: true }); } const stalled = stalledSource(); const put = writer.objects.put({ objectId: "object_late_0001", expectedGeneration: null, mediaType: "application/octet-stream", source: stalled.source, }); await stalled.streaming; const purge = purger.maintenance.enforcePolicies({ reason: "LOGOUT" }); await new Promise((resolve) => setTimeout(resolve, 20)); stalled.release(); expect(await put).toMatchObject({ ok: true }); const report = await purge; expect(report).toMatchObject({ ok: true, value: { removedObjects: count, moreObjectsAvailable: false, partitionDeleted: true, }, }); expect(report.ok && report.value.chunkSweep).toBeUndefined(); expect(filesUnder(root, scopeA)).toEqual([]); expect(await openedBytes(writer, "object_late_0001")).toBe("NOT_FOUND"); }, ); // 1103/05-01 rest (Y1a). The same gap without timing: another tab's put of // a new object commits and settles right after the purge lists the // partition, so the listing misses it and no journal row is left to count. it("takes a new object another tab's put settles between the purge's listing and its end", async () => { const { root, idb, tab } = sharedRootTabs(); const journal = createIndexedDbOpfsJournal({ authorityToken: scopeA.authorityToken, factory: idb.factory, keyRange: idb.keyRange, }); const stalled = stalledSource(); let late: ReturnType | undefined; const purger = tab("p", { ...authority, journal: { ...journal, async listCommittedObjects(request) { const page = await journal.listCommittedObjects(request); stalled.release(); await late; return page; }, }, }); const writer = tab("w", authority); expect(await putBytes(purger, "object_secret_1", [1, 2, 3])).toMatchObject({ ok: true }); late = writer.objects.put({ objectId: "object_late_0001", expectedGeneration: null, mediaType: "application/octet-stream", source: stalled.source, }); await stalled.streaming; const report = await purger.maintenance.enforcePolicies({ reason: "ACCOUNT_DELETION", }); expect(await late).toMatchObject({ ok: true, value: { generation: 1 } }); expect(report).toMatchObject({ ok: true, value: { removedObjects: 1, moreObjectsAvailable: false, partitionDeleted: true, }, }); expect(report.ok && report.value.chunkSweep).toBeUndefined(); expect(filesUnder(root, scopeA)).toEqual([]); expect(await openedBytes(purger, "object_late_0001")).toBe("NOT_FOUND"); }); // 2026-11-03 05-01. A walk the budget stops part-way is no finished purge. // It leaves the rest for the next call, unless a put or delete of the // partition is unfinished: then that call takes the partition at once. it("continues a purge the object budget stopped, and takes the partition when a put is unfinished", async () => { const { root, idb, tab } = sharedRootTabs(); const purger = tab("p", authority); for (const objectId of ["object_secret_1", "object_secret_2", "object_secret_3"]) { expect(await putBytes(purger, objectId, [1])).toMatchObject({ ok: true }); } const first = await purger.maintenance.enforcePolicies({ reason: "ACCOUNT_DELETION", maxObjects: 1, }); expect(first).toEqual({ ok: true, value: { inspectedObjects: 1, removedObjects: 1, releasedBytes: 1, moreObjectsAvailable: true, deadlineReached: false, }, }); expect(filesUnder(root, scopeA)).not.toEqual([]); // A put that died before it wrote anything leaves a PREPARING row. const journal = createIndexedDbOpfsJournal({ authorityToken: scopeA.authorityToken, factory: idb.factory, keyRange: idb.keyRange, }); expect( await journal.begin({ transactionId: "transaction_left_0001", mutation: "PUT", scope: scopeA, objectId: "object_left_0001", expectedGeneration: null, targetGeneration: 1, targetByteLength: 1, targetStoragePolicy: storagePolicy, startedAtEpochMs: 2, }), ).toMatchObject({ ok: true }); expect( await purger.maintenance.enforcePolicies({ reason: "ACCOUNT_DELETION", maxObjects: 1, }), ).toMatchObject({ ok: true, value: { inspectedObjects: 1, removedObjects: 1, moreObjectsAvailable: false, partitionDeleted: true, }, }); expect(filesUnder(root, scopeA)).toEqual([]); expect(idb.readRaw("opfs-journal", "transaction_left_0001")).toBeUndefined(); expect(await openedBytes(purger, "object_secret_3")).toBe("NOT_FOUND"); }); // 2026-11-03 05-01 X2, X2b, X3. A put that stopped before it finished leaves // its journal row and its staged files. The purge reported a completed sweep // over them; the next reconcile then committed a FILES_READY put, so the // account's file came back as a readable object. it.each([ ["stopped before commit (FILES_READY)", "commitPut", false], ["stopped while uploading (PREPARING)", "markFilesReady", false], ["whose journal row is damaged", "commitPut", true], ] as const)( "takes the partition when an approved purge finds a put %s", async (_label, failingStep, damageRow) => { const { root, idb, tab } = sharedRootTabs(); const journal = createIndexedDbOpfsJournal({ authorityToken: scopeA.authorityToken, factory: idb.factory, keyRange: idb.keyRange, }); const writerWorker = loopbackGateway( createOpfsWorkerRuntime({ root: root as unknown as FileSystemDirectoryHandle, crypto: globalThis.crypto, policy: runtimePolicy, leaseManager: exclusiveLeases(), dedicatedWorker: true, supportsSynchronousAccessHandles: false, }), ); const unavailable = async () => browserDataFailure("UNAVAILABLE", "INDEXEDDB_WRITE", { retryable: true, recovery: "RETRY", }); // The tab crashes at this step: the journal write never lands and, // before commit, its compensation never runs either. const writer = tab("w", { journal: { ...journal, [failingStep]: unavailable } as OpfsJournalPort, worker: { ...writerWorker, abortPreparedPut: async () => browserDataFailure("UNAVAILABLE", "OBJECT_WRITE", { retryable: true, recovery: "RETRY", }), }, }); const purger = tab("p", authority); expect(await putBytes(purger, "object_secret_1", [1, 2, 3])).toMatchObject({ ok: true }); expect(await putBytes(writer, "object_dead_0001", [9, 9, 9])).toMatchObject({ ok: false, }); expect(idb.readRaw("opfs-journal", "transaction_w_1")).toBeDefined(); if (damageRow) { idb.seed("opfs-journal", { ...(idb.readRaw("opfs-journal", "transaction_w_1") as object), phase: "GARBLED", }); } const report = await purger.maintenance.enforcePolicies({ reason: "ACCOUNT_DELETION", }); expect(report).toMatchObject({ ok: true, value: { moreObjectsAvailable: false, partitionDeleted: true }, }); expect(filesUnder(root, scopeA)).toEqual([]); expect(idb.readRaw("opfs-journal", "transaction_w_1")).toBeUndefined(); // Nothing is left for a later reconcile to bring back. expect(await purger.maintenance.reconcile()).toMatchObject({ ok: true, value: { committedTransactions: 0, corruptTransactions: 0 }, }); expect(await openedBytes(purger, "object_dead_0001")).toBe("NOT_FOUND"); expect(filesUnder(root, scopeA)).toEqual([]); }, ); // 1103/05-01 rest (Y2). The journal counts rows by their partition key, so a // stopped put whose row lost that key was never counted. Its staging // receipt kept its chunk out of the sweep, and every purge said COMPLETED // with the receipt, the chunk and the manifest still on disk. The partition // delete takes them; the keyless row itself stays, counted apart (05-03). it("leaves no bytes of a stopped put whose journal row lost its partition key", async () => { const { root, idb, tab } = sharedRootTabs(); const journal = createIndexedDbOpfsJournal({ authorityToken: scopeA.authorityToken, factory: idb.factory, keyRange: idb.keyRange, }); const writerWorker = loopbackGateway( createOpfsWorkerRuntime({ root: root as unknown as FileSystemDirectoryHandle, crypto: globalThis.crypto, policy: runtimePolicy, leaseManager: exclusiveLeases(), dedicatedWorker: true, supportsSynchronousAccessHandles: false, }), ); const unavailable = async () => browserDataFailure("UNAVAILABLE", "INDEXEDDB_WRITE", { retryable: true, recovery: "RETRY", }); // The tab crashes before commit: neither the commit nor its compensation // lands, so the row stays FILES_READY with its staging on disk. const writer = tab("w", { journal: { ...journal, commitPut: unavailable } as OpfsJournalPort, worker: { ...writerWorker, abortPreparedPut: async () => browserDataFailure("UNAVAILABLE", "OBJECT_WRITE", { retryable: true, recovery: "RETRY", }), }, }); const purger = tab("p", authority); expect(await putBytes(purger, "object_secret_1", [1, 2, 3])).toMatchObject({ ok: true }); expect(await putBytes(writer, "object_dead_0001", [9, 9, 9])).toMatchObject({ ok: false, }); const { logicalKey: _dropped, ...keyless } = idb.readRaw( "opfs-journal", "transaction_w_1", ) as Record; idb.seed("opfs-journal", keyless); expect(filesUnder(root, scopeA)).not.toEqual([]); for (let run = 0; run < 2; run += 1) { const report = await purger.maintenance.enforcePolicies({ reason: "ACCOUNT_DELETION", }); expect(report).toMatchObject({ ok: true, value: { moreObjectsAvailable: false, partitionDeleted: true }, }); expect(report.ok && report.value.chunkSweep).toBeUndefined(); expect(filesUnder(root, scopeA)).toEqual([]); expect(await purger.maintenance.reconcile()).toMatchObject({ ok: true, value: { committedTransactions: 0, corruptTransactions: 1, unattributedCorruptTransactions: 1, }, }); } expect(await openedBytes(purger, "object_dead_0001")).toBe("NOT_FOUND"); expect(idb.readRaw("opfs-journal", "transaction_w_1")).toBeDefined(); }); // [0929] 05-02. Another tab overwrites the object the purge is removing, so // the purge's remove ends in CONFLICT. That purge is not finished and must // not claim to be. The overwrite finishes between the purge's listing and // its remove: one still running when the purge checks the journal sends it // to the partition delete instead (2026-11-03 05-01). The next call walks // every object and takes the partition (1103/05-01 rest). it("reports a purge that skipped a changing object as unfinished", async () => { const { root, idb, tab } = sharedRootTabs(); const journal = createIndexedDbOpfsJournal({ authorityToken: scopeA.authorityToken, factory: idb.factory, keyRange: idb.keyRange, }); const stalled = stalledSource(); let overwrite: ReturnType | undefined; const purger = tab("p", { ...authority, journal: { ...journal, async listCommittedObjects(request) { const page = await journal.listCommittedObjects(request); stalled.release(); await overwrite; return page; }, }, }); const writer = tab("w", authority); expect(await putBytes(writer, "object_secret_1", [1, 2, 3])).toMatchObject({ ok: true }); overwrite = writer.objects.put({ objectId: "object_secret_1", expectedGeneration: 1, mediaType: "application/octet-stream", source: stalled.source, }); await stalled.streaming; const purge = purger.maintenance.enforcePolicies({ reason: "ACCOUNT_DELETION" }); expect(await overwrite).toMatchObject({ ok: true }); const first = await purge; expect(first).toMatchObject({ ok: true, value: { inspectedObjects: 1, removedObjects: 0, moreObjectsAvailable: true }, }); expect(first.ok && first.value.chunkSweep).toBeUndefined(); expect( await purger.maintenance.enforcePolicies({ reason: "ACCOUNT_DELETION" }), ).toMatchObject({ ok: true, value: { removedObjects: 1, moreObjectsAvailable: false, partitionDeleted: true, }, }); expect(filesUnder(root, scopeA)).toEqual([]); }); // [0929] 05-01. A journal row the purge cannot read used to fail the whole // purge, so not even the readable objects went and the partition's bytes // stayed for good. The row is now skipped and counted, and an approved // LOGOUT or ACCOUNT_DELETION that cannot finish because of it removes the // partition directory and that partition's journal rows instead. const corruptObjectRow = (scope: OpfsStorageScope, objectId: string) => { const scopeKey = [ scope.authorityToken, scope.namespaceToken, scope.partitionToken, ].join("|"); return { logicalKey: `${scopeKey}|${objectId}`, scopeObjectKey: `${scopeKey}|${objectId}`, scopeKey, objectId, preparedObject: { corrupt: true }, }; }; it.each(["LOGOUT", "ACCOUNT_DELETION"] as const)( "removes the partition when a corrupt object row stops an approved %s purge", async (reason) => { const { root, idb, tab } = sharedRootTabs(); const purged = tab("p", authority); const kept = tab("k", { ...authority, scope: scopeP2 }); expect(await putBytes(purged, "object_secret_1", [1, 2, 3])).toMatchObject({ ok: true }); expect(await putBytes(purged, "object_secret_2", [4, 5])).toMatchObject({ ok: true }); expect(await putBytes(kept, "object_kept_0001", [7, 7])).toMatchObject({ ok: true }); idb.seed("opfs-objects", corruptObjectRow(scopeA, "object_secret_2")); const report = await purged.maintenance.enforcePolicies({ reason }); expect(report).toEqual({ ok: true, value: { inspectedObjects: 1, removedObjects: 1, releasedBytes: 3, moreObjectsAvailable: false, deadlineReached: false, corruptObjects: 1, partitionDeleted: true, }, }); expect(filesUnder(root, scopeA)).toEqual([]); expect(await openedBytes(kept, "object_kept_0001")).toEqual({ generation: 1, bytes: [7, 7], }); // The partition starts over: its journal rows went with its files. expect(await putBytes(purged, "object_secret_2", [9])).toMatchObject({ ok: true, value: { generation: 1 }, }); expect(await openedBytes(purged, "object_secret_2")).toEqual({ generation: 1, bytes: [9], }); }, ); it("never removes a corrupt partition for a purge the authority refused", async () => { const { root, idb, tab } = sharedRootTabs(); const writer = tab("w", authority); expect(await putBytes(writer, "object_secret_1", [1, 2, 3])).toMatchObject({ ok: true }); expect(await putBytes(writer, "object_secret_2", [4, 5])).toMatchObject({ ok: true }); idb.seed("opfs-objects", corruptObjectRow(scopeA, "object_secret_2")); const refused = tab("r", { requestMaintenanceAuthority: () => ({ authorized: false as const }), consumeMaintenanceAuthority: () => true, }); expect( await refused.maintenance.enforcePolicies({ reason: "ACCOUNT_DELETION" }), ).toMatchObject({ ok: false, error: { code: "POLICY_REJECTED" } }); expect(filesUnder(root, scopeA)).not.toEqual([]); expect(await openedBytes(writer, "object_secret_1")).toEqual({ generation: 1, bytes: [1, 2, 3], }); }); it("reconciles the other rows and sweeps orphans past a corrupt journal row", async () => { const { root, idb, tab } = sharedRootTabs(); const store = tab("r"); expect(await putBytes(store, "object_secret_1", [1, 2, 3])).toMatchObject({ ok: true }); const journal = createIndexedDbOpfsJournal({ authorityToken: scopeA.authorityToken, factory: idb.factory, keyRange: idb.keyRange, }); // A put that died before it wrote anything leaves a PREPARING row. expect( await journal.begin({ transactionId: "transaction_left_0001", mutation: "PUT", scope: scopeA, objectId: "object_left_0001", expectedGeneration: null, targetGeneration: 1, targetByteLength: 1, targetStoragePolicy: storagePolicy, startedAtEpochMs: 2, }), ).toMatchObject({ ok: true }); idb.seed("opfs-journal", { transactionId: "transaction_corrupt1", startedAtEpochMs: 1, corrupt: true, }); const orphan = "0".repeat(64); await seedChunk(root, scopeA, orphan); expect(await store.maintenance.reconcile()).toMatchObject({ ok: true, value: { inspectedTransactions: 1, failedTransactions: 0, corruptTransactions: 1, deletedOrphanChunks: 1, orphanGcStatus: "COMPLETED", }, }); expect(root.has(chunkFilePath(scopeA, orphan))).toBe(false); expect(idb.readRaw("opfs-journal", "transaction_left_0001")).toBeUndefined(); expect(idb.readRaw("opfs-journal", "transaction_corrupt1")).toMatchObject({ corrupt: true, }); }); // 2026-11-03 05-03 X4. A damaged journal row without a readable partition // key outlives every approved partition delete. It used to keep each // reconcile DEGRADED for good, with nothing the runbook lets anyone do. It // is now counted apart and kept out of the partition damage signal; a row // its partition delete would take still raises it. it("reports a damaged journal row no partition owns apart from partition damage", async () => { const { root, idb, tab } = sharedRootTabs(); const outcomes: string[] = []; const store = tab("s", { ...authority, observer: (observation) => { if ( observation.operation === "OBJECT_RECONCILE" && observation.outcome !== "STARTED" ) { outcomes.push(`${observation.outcome}:${observation.failureCode ?? ""}`); } }, }); expect(await putBytes(store, "object_secret_1", [1, 2, 3])).toMatchObject({ ok: true }); idb.seed("opfs-objects", corruptObjectRow(scopeA, "object_secret_2")); idb.seed("opfs-journal", { transactionId: "transaction_corrupt1", startedAtEpochMs: 1, corrupt: true, }); expect( await store.maintenance.enforcePolicies({ reason: "ACCOUNT_DELETION" }), ).toMatchObject({ ok: true, value: { partitionDeleted: true } }); expect(filesUnder(root, scopeA)).toEqual([]); expect(idb.readRaw("opfs-journal", "transaction_corrupt1")).toMatchObject({ corrupt: true, }); expect(await store.maintenance.reconcile()).toMatchObject({ ok: true, value: { corruptTransactions: 1, unattributedCorruptTransactions: 1 }, }); expect(outcomes).toEqual(["SUCCEEDED:"]); idb.seed("opfs-journal", { transactionId: "transaction_keyed001", logicalKey: `${scopeA.authorityToken}|${scopeA.namespaceToken}|${scopeA.partitionToken}|object_secret_3`, startedAtEpochMs: 2, phase: "GARBLED", }); expect(await store.maintenance.reconcile()).toMatchObject({ ok: true, value: { corruptTransactions: 2, unattributedCorruptTransactions: 1 }, }); expect(outcomes.at(-1)).toBe("DEGRADED:CORRUPT_DATA"); }); it("removes a partition directory only under the origin mutation lease", async () => { const root = new MemoryDirectory(); const leases = exclusiveLeases(); const runtime = createOpfsWorkerRuntime({ root: root as unknown as FileSystemDirectoryHandle, crypto: globalThis.crypto, policy: runtimePolicy, leaseManager: leases, dedicatedWorker: true, supportsSynchronousAccessHandles: false, }); await seedChunk(root, scopeA, "0".repeat(64)); await seedChunk(root, scopeP2, "0".repeat(64)); const partitionPath = (scope: OpfsStorageScope) => [ "authorities", scope.authorityToken, scope.namespaceToken, scope.partitionToken, ]; const held = await leases.acquire(); let settled = false; const removal = runtime .handleRequest({ requestId: "request_remove_partition", protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, kind: "REMOVE_PARTITION", scope: scopeA, }) .finally(() => { settled = true; }); await new Promise((resolve) => setTimeout(resolve, 10)); expect(settled).toBe(false); expect(root.has(partitionPath(scopeA))).toBe(true); held.release(); expect(await removal).toMatchObject({ ok: true, kind: "REMOVE_PARTITION" }); expect(root.has(partitionPath(scopeA))).toBe(false); expect(root.has(partitionPath(scopeP2))).toBe(true); expect(leases.held).toBe(false); }); // [0929] 05-01. The origin lease covers a put only from BEGIN to FINISH, and // the partition delete runs in two steps: the directory under that lease, // then the journal rows. Another tab's put that had begun before the purge // was not checked once it left the lease. Each case parks that put at a // journal step past FINISH, and optionally lets the purge remove the // directory before the put reaches BEGIN, so the rows go while it is parked. it.each([ ["markFilesReady", false], ["commitPut", false], ["markFilesReady", true], ["commitPut", true], ["complete", true], ] as const)( "leaves no partition bytes when an approved purge meets another tab's put parked before %s (directory removed before its BEGIN: %s)", async (parkedStep, directoryFirst) => { const { root, leases, idb, tab } = sharedRootTabs(); const runtime = () => createOpfsWorkerRuntime({ root: root as unknown as FileSystemDirectoryHandle, crypto: globalThis.crypto, policy: runtimePolicy, leaseManager: leases, dedicatedWorker: true, supportsSynchronousAccessHandles: false, }); const journal = createIndexedDbOpfsJournal({ authorityToken: scopeA.authorityToken, factory: idb.factory, keyRange: idb.keyRange, }); const beforeBegin = checkpoint(); const parked = checkpoint(); const rowsPending = checkpoint(); const writerWorker = loopbackGateway(runtime()); const writer = tab("w", { journal: { ...journal, [parkedStep]: async ( ...input: Parameters ) => { await parked.pass(); return await ( journal[parkedStep] as (...args: typeof input) => unknown )(...input); }, } as OpfsJournalPort, worker: { ...writerWorker, async preparePut(input) { if (directoryFirst) await beforeBegin.pass(); return await writerWorker.preparePut(input); }, }, }); const purgerWorker = loopbackGateway(runtime()); const purger = tab("p", { ...authority, worker: { ...purgerWorker, async removePartition(scope, signal) { const removed = await purgerWorker.removePartition(scope, signal); await rowsPending.pass(); return removed; }, }, }); expect(await putBytes(purger, "object_secret_1", [1, 2, 3])).toMatchObject({ ok: true }); idb.seed("opfs-objects", corruptObjectRow(scopeA, "object_secret_2")); const settle = (step: Promise) => Promise.race([ step, new Promise((resolve) => setTimeout(resolve, 100)), ]); const put = putBytes(writer, "object_inflight1", [8, 8]); let purge: ReturnType; if (directoryFirst) { // The put's journal row is PREPARING; it has written nothing yet. await beforeBegin.reached; purge = purger.maintenance.enforcePolicies({ reason: "ACCOUNT_DELETION" }); await settle(rowsPending.reached); beforeBegin.open(); await parked.reached; } else { await parked.reached; purge = purger.maintenance.enforcePolicies({ reason: "ACCOUNT_DELETION" }); } rowsPending.open(); await settle(purge); parked.open(); const [report, written] = await Promise.all([purge, put]); // The put lies wholly before the partition delete, which then takes it. expect(written).toMatchObject({ ok: true, value: { generation: 1 } }); expect(report).toMatchObject({ ok: true, value: { partitionDeleted: true, moreObjectsAvailable: false }, }); expect(filesUnder(root, scopeA)).toEqual([]); expect(idb.readRaw("opfs-journal", "transaction_w_1")).toBeUndefined(); expect(await openedBytes(writer, "object_inflight1")).toBe("NOT_FOUND"); }, ); it("stops a partition delete that waits on another tab's put when the purge is aborted", async () => { const { root, idb, tab } = sharedRootTabs(); const purger = tab("p", authority); expect(await putBytes(purger, "object_secret_1", [1, 2, 3])).toMatchObject({ ok: true }); idb.seed("opfs-objects", corruptObjectRow(scopeA, "object_secret_2")); const lockName = `${runtimePolicy.mutationLockName}:partition:${scopeA.authorityToken}:${scopeA.namespaceToken}:${scopeA.partitionToken}`; const putHolding = checkpoint(); // Stands in for a put of this partition in another tab. const holder = navigator.locks.request(lockName, { mode: "shared" }, () => putHolding.pass(), ); await putHolding.reached; const controller = new AbortController(); const purge = purger.maintenance.enforcePolicies({ reason: "ACCOUNT_DELETION", signal: controller.signal, }); while ( !(await navigator.locks.query()).pending?.some( (lock) => lock.name === lockName && lock.mode === "exclusive", ) ) { await new Promise((resolve) => setTimeout(resolve, 1)); } controller.abort(); expect(await purge).toMatchObject({ ok: false, error: { code: "ABORTED" } }); expect(filesUnder(root, scopeA)).not.toEqual([]); putHolding.open(); await holder; }); }); // 2026-11-03 05-02. A put or delete queued behind a partition delete held the // partition lock request without its caller's signal and without a bound, so // cancelling it did nothing until the delete let go. describe("05-02 a put or delete waiting on the partition lock", () => { const lockName = (policy: typeof runtimePolicy) => `${policy.mutationLockName}:partition:${scopeA.authorityToken}:${scopeA.namespaceToken}:${scopeA.partitionToken}`; afterEach(() => { vi.useRealTimers(); }); /** Another tab's partition delete holds the lock until `release`. */ async function heldPartitionLock(policy: typeof runtimePolicy) { const holding = checkpoint(); const holder = navigator.locks.request( lockName(policy), { mode: "exclusive" }, () => holding.pass(), ); await holding.reached; return { async release() { holding.open(); await holder; }, }; } async function queuedOnPartitionLock( policy: typeof runtimePolicy, tick: () => Promise, ) { while ( !(await navigator.locks.query()).pending?.some( (lock) => lock.name === lockName(policy) && lock.mode === "shared", ) ) { await tick(); } } const settledWithin = async (work: Promise, ms: number) => await Promise.race([ work, new Promise<"STILL_WAITING">((resolve) => setTimeout(() => resolve("STILL_WAITING"), ms), ), ]); it("ends a queued put and a queued delete as soon as their caller aborts", async () => { const { tab } = sharedRootTabs(); const store = tab("s"); expect( await store.objects.put({ objectId: "object_kept_0001", expectedGeneration: null, mediaType: "application/octet-stream", source: oneByteSource(), }), ).toMatchObject({ ok: true }); const held = await heldPartitionLock(runtimePolicy); const controller = new AbortController(); const put = store.objects.put({ objectId: "object_aborted01", expectedGeneration: null, mediaType: "application/octet-stream", source: oneByteSource(), signal: controller.signal, }); const removal = store.objects.remove({ objectId: "object_kept_0001", expectedGeneration: 1, signal: controller.signal, }); await queuedOnPartitionLock( runtimePolicy, () => new Promise((resolve) => setTimeout(resolve, 1)), ); controller.abort(); expect(await settledWithin(put, 200)).toMatchObject({ ok: false, error: { code: "ABORTED", operation: "OBJECT_WRITE" }, }); expect(await settledWithin(removal, 200)).toMatchObject({ ok: false, error: { code: "ABORTED", operation: "OBJECT_DELETE" }, }); await held.release(); expect(await openedBytes(store, "object_aborted01")).toBe("NOT_FOUND"); expect(await openedBytes(store, "object_kept_0001")).toEqual({ generation: 1, bytes: [6], }); }); it("ends a partition lock wait at the policy bound as a retryable BLOCKED", async () => { const policy = resolveOpfsRuntimePolicy({ ...runtimePolicy, mutationLockWaitTimeoutMs: 300_000, }); const { tab } = sharedRootTabs(policy); const store = tab("s"); const held = await heldPartitionLock(policy); vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] }); const put = store.objects.put({ objectId: "object_blocked01", expectedGeneration: null, mediaType: "application/octet-stream", source: oneByteSource(), }); await queuedOnPartitionLock(policy, () => vi.advanceTimersByTimeAsync(1)); await vi.advanceTimersByTimeAsync(policy.mutationLockWaitTimeoutMs); expect(await put).toMatchObject({ ok: false, error: { code: "BLOCKED", operation: "OBJECT_WRITE", retryable: true }, }); vi.useRealTimers(); await held.release(); }); }); /** A step that parks until opened and says when something reached it. */ function checkpoint(): Readonly<{ reached: Promise; pass: () => Promise; open: () => void; }> { let reach!: () => void; const reached = new Promise((resolve) => { reach = resolve; }); let open!: () => void; const opened = new Promise((resolve) => { open = resolve; }); return { reached, open, async pass() { reach(); await opened; }, }; } describe("05-07 a put whose source stops lets go of the origin lock", () => { afterEach(() => { vi.useRealTimers(); }); it("fails the stalled put at the idle bound so another tab's put runs", async () => { const policy = resolveOpfsRuntimePolicy({ ...runtimePolicy, putIdleTimeoutMs: 30_000, }); vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] }); const { tab, leases } = sharedRootTabs(policy); const tabA = tab("a"); const tabB = tab("b"); const stalled = stalledSource(); const putA = tabA.objects.put({ objectId: "object_stalled_01", expectedGeneration: null, mediaType: "application/octet-stream", source: stalled.source, }); await stalled.streaming; expect(leases.held).toBe(true); const putB = tabB.objects.put({ objectId: "object_waiting_01", expectedGeneration: null, mediaType: "application/octet-stream", source: oneByteSource(), }); await vi.advanceTimersByTimeAsync(policy.putIdleTimeoutMs + 1); vi.useRealTimers(); const settledA = await Promise.race([ putA, new Promise((resolve) => setTimeout(() => resolve("STILL_RUNNING"), 2_000)), ]); expect(settledA).toMatchObject({ ok: false, error: { code: "NOT_READABLE", retryable: true }, }); expect(await putB).toMatchObject({ ok: true, value: { generation: 1 } }); stalled.release(); }); // [0929] 05-09. The test above holds only while a queued writer outlasts a // stalled one. That ordering was a comment; a policy that breaks it is now // refused when it is resolved. it.each([ ["equal to", 60_000], ["longer than", 120_000], ])("rejects an idle bound %s the lock wait", (_, putIdleTimeoutMs) => { expect(() => resolveOpfsRuntimePolicy({ ...runtimePolicy, mutationLockWaitTimeoutMs: 60_000, putIdleTimeoutMs, }), ).toThrow(TypeError); expect( resolveOpfsRuntimePolicy({ ...runtimePolicy, mutationLockWaitTimeoutMs: putIdleTimeoutMs + 1, putIdleTimeoutMs, }).putIdleTimeoutMs, ).toBe(putIdleTimeoutMs); }); }); describe("05-10 the object id grammar is the prepared-object grammar", () => { it("rejects a policy that widens the object id grammar when it is resolved", () => { expect(() => resolveOpfsRuntimePolicy({ ...runtimePolicy, isObjectIdAllowed: (objectId) => /^[A-Za-z0-9_.-]{1,200}$/u.test(objectId), }), ).toThrow(TypeError); }); it.each([ ["a colon", /^[A-Za-z0-9_:-]{8,128}$/u], ["an at sign", /^[A-Za-z0-9_@-]{8,128}$/u], ["Unicode letters", /^[\p{L}0-9_-]{8,128}$/u], ])("rejects a policy that also allows %s when it is resolved", (_, grammar) => { expect(() => resolveOpfsRuntimePolicy({ ...runtimePolicy, isObjectIdAllowed: (objectId) => grammar.test(objectId), }), ).toThrow(TypeError); }); // A predicate can widen the grammar in ways no sample finds. The grammar // still applies at BEGIN_PUT, so such an id never reaches FINISH_PUT. const widenedId = "object:tenant@12345"; const widenedPolicy = (): typeof runtimePolicy => ({ ...runtimePolicy, isObjectIdAllowed: (objectId) => objectId === widenedId || runtimePolicy.isObjectIdAllowed(objectId), }); it("refuses an id outside the grammar at BEGIN_PUT even if the policy allows it", async () => { const runtime = createOpfsWorkerRuntime({ root: new MemoryDirectory() as unknown as FileSystemDirectoryHandle, crypto: globalThis.crypto, policy: widenedPolicy(), leaseManager: immediateLeases({ count: 0 }), dedicatedWorker: true, supportsSynchronousAccessHandles: false, }); expectFailureCode( await runtime.handleRequest({ ...beginRequest("request_begin_1234", "transaction_12345678", scopeA), objectId: widenedId, } as OpfsWorkerRequest), "INVALID_INPUT", ); }); it("fails such a put as invalid input before it writes, never as corrupt data", async () => { const { tab, root } = sharedRootTabs(widenedPolicy()); const adapter = tab("a"); expect( await adapter.objects.put({ objectId: widenedId, expectedGeneration: null, mediaType: "application/octet-stream", source: oneByteSource(), }), ).toMatchObject({ ok: false, error: { code: "INVALID_INPUT" } }); expect(root.children.size).toBe(0); expect(await adapter.objects.put({ objectId: "object_12345678", expectedGeneration: null, mediaType: "application/octet-stream", source: oneByteSource(), })).toMatchObject({ ok: true }); }); }); describe("05-14 a read that outlives its generation", () => { it("ends with NOT_FOUND / REHYDRATE once GC took the replaced chunks, and a reopen reads the new generation", async () => { const { root, tab } = sharedRootTabs(); const store = tab("r"); const put = (bytes: number[], expectedGeneration: number | null) => store.objects.put({ objectId: "object_12345678", expectedGeneration, mediaType: "application/octet-stream", source: bytesSource(new Uint8Array(bytes)), }); expect(await put([1], null)).toMatchObject({ ok: true }); const opened = await store.objects.open({ objectId: "object_12345678" }); if (!opened.ok) throw new Error(opened.error.code); // Generation 2 replaces it, and its old chunk is past the GC grace. expect(await put([2], 1)).toMatchObject({ ok: true }); const digest = Array.from( new Uint8Array( await globalThis.crypto.subtle.digest("SHA-256", new Uint8Array([1])), ), (byte) => byte.toString(16).padStart(2, "0"), ).join(""); memoryFileAt(root, chunkFilePath(scopeA, digest)).lastModified = 0; expect(await store.maintenance.reconcile()).toMatchObject({ ok: true, value: { deletedOrphanChunks: 1 }, }); const chunks = []; for await (const chunk of opened.value.source.stream( new AbortController().signal, )) { chunks.push(chunk); } expect(chunks).toEqual([ expect.objectContaining({ ok: false, error: expect.objectContaining({ code: "NOT_FOUND", recovery: "REHYDRATE", }), }), ]); expect(await openedBytes(store, "object_12345678")).toEqual({ generation: 2, bytes: [2], }); }); });