diff --git a/src/adapters/storage/opfs/opfs-byte-store-adapter.ts b/src/adapters/storage/opfs/opfs-byte-store-adapter.ts index c551bbd6..cb755ffa 100644 --- a/src/adapters/storage/opfs/opfs-byte-store-adapter.ts +++ b/src/adapters/storage/opfs/opfs-byte-store-adapter.ts @@ -1096,25 +1096,69 @@ export function createOpfsByteStoreAdapter( 0, now() - policy.orphanGracePeriodMs, ); - const candidates = await dependencies.worker.listOrphanCandidates( - dependencies.scope, - olderThanEpochMs, - policy.orphanGcBatchSize, - signal, - ); - if (!candidates.ok) return candidates; - if (!candidates.value.safeToSweep) { - return browserDataSuccess({ - inspected: 0, - deleted: 0, - status: "STAGING_STATE_UNREADABLE", - }); - } let inspected = 0; let deleted = 0; - for (const digestHex of candidates.value.digests) { - if (signal?.aborted) { - return browserDataFailure("ABORTED", "OBJECT_RECONCILE"); + // R-5.1. Candidates include committed chunks, so a page can be all + // referenced. The scan pages on by digest cursor until it runs out or the + // deadline stops it. + // ponytail: every reconcile restarts at the lowest digest; if checking the + // referenced chunks alone outlasts the budget, keep the cursor across calls. + let afterDigest: string | undefined; + for (;;) { + const candidates = await dependencies.worker.listOrphanCandidates( + dependencies.scope, + olderThanEpochMs, + policy.orphanGcBatchSize, + signal, + afterDigest, + ); + if (!candidates.ok) return candidates; + if (!candidates.value.safeToSweep) { + return browserDataSuccess({ + inspected, + deleted, + status: "STAGING_STATE_UNREADABLE", + }); + } + for (const digestHex of candidates.value.digests) { + if (signal?.aborted) { + return browserDataFailure("ABORTED", "OBJECT_RECONCILE"); + } + if (now() >= deadline) { + return browserDataSuccess({ + inspected, + deleted, + status: "DEADLINE_REACHED", + }); + } + inspected += 1; + const referenced = await dependencies.journal.isChunkReferenced( + dependencies.scope, + digestHex, + ); + if (!referenced.ok) { + return rebaseFailure(referenced.error, "OBJECT_RECONCILE"); + } + if (referenced.value) continue; + const removal = await dependencies.worker.deleteOrphanChunk( + dependencies.scope, + digestHex, + olderThanEpochMs, + signal, + ); + if (!removal.ok) return removal; + if (removal.value.skippedUnsafe) { + return browserDataSuccess({ + inspected, + deleted, + status: "STAGING_STATE_UNREADABLE", + }); + } + if (removal.value.deleted) deleted += 1; + } + afterDigest = candidates.value.digests.at(-1); + if (!candidates.value.moreAvailable || afterDigest === undefined) { + return browserDataSuccess({ inspected, deleted, status: "COMPLETED" }); } if (now() >= deadline) { return browserDataSuccess({ @@ -1123,39 +1167,7 @@ export function createOpfsByteStoreAdapter( status: "DEADLINE_REACHED", }); } - inspected += 1; - const referenced = await dependencies.journal.isChunkReferenced( - dependencies.scope, - digestHex, - ); - if (!referenced.ok) { - return rebaseFailure(referenced.error, "OBJECT_RECONCILE"); - } - if (referenced.value) continue; - const removal = await dependencies.worker.deleteOrphanChunk( - dependencies.scope, - digestHex, - olderThanEpochMs, - signal, - ); - if (!removal.ok) return removal; - if (removal.value.skippedUnsafe) { - return browserDataSuccess({ - inspected, - deleted, - status: "STAGING_STATE_UNREADABLE", - }); - } - if (removal.value.deleted) deleted += 1; } - return browserDataSuccess({ - inspected, - deleted, - status: - candidates.value.moreAvailable - ? "DEADLINE_REACHED" - : "COMPLETED", - }); } } diff --git a/src/adapters/storage/opfs/opfs-worker-client.ts b/src/adapters/storage/opfs/opfs-worker-client.ts index 47ce2978..43db8f25 100644 --- a/src/adapters/storage/opfs/opfs-worker-client.ts +++ b/src/adapters/storage/opfs/opfs-worker-client.ts @@ -440,6 +440,7 @@ export function createOpfsWorkerGateway( olderThanEpochMs: number, maxEntries: number, signal?: AbortSignal, + afterDigest?: string, ) { return await invoke( "OBJECT_RECONCILE", @@ -448,6 +449,7 @@ export function createOpfsWorkerGateway( scope, olderThanEpochMs, maxEntries, + ...(afterDigest === undefined ? {} : { afterDigest }), }, signal, [], diff --git a/src/adapters/storage/opfs/opfs-worker-protocol.ts b/src/adapters/storage/opfs/opfs-worker-protocol.ts index 6dccaa9f..70062c06 100644 --- a/src/adapters/storage/opfs/opfs-worker-protocol.ts +++ b/src/adapters/storage/opfs/opfs-worker-protocol.ts @@ -120,6 +120,12 @@ export type OpfsWorkerRequest = scope: OpfsStorageScope; olderThanEpochMs: number; maxEntries: number; + /** + * R-5.1. Candidates come back in ascending digest order. The next page + * starts strictly after this digest (the last one of the previous page), + * so a batch of still-referenced chunks cannot hide the rest forever. + */ + afterDigest?: string; }> | Readonly<{ requestId: string; @@ -239,6 +245,7 @@ export interface OpfsWorkerGateway { olderThanEpochMs: number, maxEntries: number, signal?: AbortSignal, + afterDigest?: string, ): Promise>; deleteOrphanChunk( scope: OpfsStorageScope, diff --git a/src/adapters/storage/opfs/opfs-worker-runtime.ts b/src/adapters/storage/opfs/opfs-worker-runtime.ts index 50b93e36..99c4accf 100644 --- a/src/adapters/storage/opfs/opfs-worker-runtime.ts +++ b/src/adapters/storage/opfs/opfs-worker-runtime.ts @@ -289,6 +289,7 @@ export function createOpfsWorkerRuntime( request.scope, request.olderThanEpochMs, request.maxEntries, + request.afterDigest, ), ); case "DELETE_ORPHAN_CHUNK": @@ -952,6 +953,7 @@ export function createOpfsWorkerRuntime( scope: OpfsPreparedObject["descriptor"]["scope"], olderThanEpochMs: number, maxEntries: number, + afterDigest: string | undefined, ): Promise { assertWorkerAvailable(); if ( @@ -960,7 +962,9 @@ export function createOpfsWorkerRuntime( olderThanEpochMs < 0 || !Number.isSafeInteger(maxEntries) || maxEntries < 1 || - maxEntries > dependencies.policy.orphanGcBatchSize + maxEntries > dependencies.policy.orphanGcBatchSize || + (afterDigest !== undefined && + (typeof afterDigest !== "string" || !SHA256_HEX.test(afterDigest))) ) { throw new OpfsRuntimeFailure("INVALID_INPUT"); } @@ -991,25 +995,33 @@ export function createOpfsWorkerRuntime( } throw error; } + // R-5.1. Directory order is unspecified, so the scan walks prefixes and + // names in ascending order; that is what makes `afterDigest` a cursor. + const cursor = afterDigest ?? ""; + const prefixes = new Map(); + for await (const [name, handle] of shaRoot.entries()) { + if (handle.kind !== "directory" || name < cursor.slice(0, 2)) continue; + prefixes.set(name, handle as FileSystemDirectoryHandle); + } const candidates: string[] = []; - outer: for await (const [, prefixHandle] of shaRoot.entries()) { - if (prefixHandle.kind !== "directory") continue; - const prefixDirectory = - prefixHandle as FileSystemDirectoryHandle; - for await (const [name, handle] of prefixDirectory.entries()) { + outer: for (const prefix of [...prefixes.keys()].sort()) { + const files = new Map(); + for await (const [name, handle] of prefixes.get(prefix)!.entries()) { if (handle.kind !== "file") continue; const digestHex = name.endsWith(".bin") ? name.slice(0, -4) : ""; if ( !SHA256_HEX.test(digestHex) || + digestHex <= cursor || staged.digests.has(digestHex) ) { continue; } - const file = await ( - handle as FileSystemFileHandle - ).getFile(); + files.set(digestHex, handle as FileSystemFileHandle); + } + for (const digestHex of [...files.keys()].sort()) { + const file = await files.get(digestHex)!.getFile(); if (file.lastModified > olderThanEpochMs) continue; candidates.push(digestHex); if (candidates.length > maxEntries) break outer; diff --git a/tests/unit/opfs-byte-store.test.ts b/tests/unit/opfs-byte-store.test.ts index 731d7d51..4a30a0dc 100644 --- a/tests/unit/opfs-byte-store.test.ts +++ b/tests/unit/opfs-byte-store.test.ts @@ -1100,11 +1100,13 @@ describe("OPFS byte-store coordinator", () => { orphanGcStatus: "COMPLETED", }, }); + // The first page carries no cursor. expect(listOrphans).toHaveBeenCalledWith( scope, expect.any(Number), expect.any(Number), undefined, + undefined, ); expect(deleteOrphan).toHaveBeenCalledWith( scope, diff --git a/tests/unit/opfs-worker-runtime.test.ts b/tests/unit/opfs-worker-runtime.test.ts index eb419e2e..d3fb7609 100644 --- a/tests/unit/opfs-worker-runtime.test.ts +++ b/tests/unit/opfs-worker-runtime.test.ts @@ -1,6 +1,7 @@ import { describe, expect, it } from "vitest"; import type { + OpfsJournalPort, OpfsPreparedObject, OpfsPhysicalGenerationId, OpfsStorageScope, @@ -8,6 +9,8 @@ import type { import type { BrowserStoragePolicy, } from "../../src/application/ports/browser-file-storage/shared.ts"; +import { browserDataSuccess } from "../../src/adapters/browser-file-storage/result.ts"; +import { createOpfsByteStoreAdapter } from "../../src/adapters/storage/opfs/opfs-byte-store-adapter.ts"; import { resolveOpfsRuntimePolicy, } from "../../src/adapters/storage/opfs/opfs-policy.ts"; @@ -17,6 +20,7 @@ import { } 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"; @@ -25,6 +29,7 @@ import { startBrowserOpfsDedicatedWorker, type OpfsMutationLeaseManager, type OpfsWorkerMessageHost, + type OpfsWorkerRuntime, } from "../../src/adapters/storage/opfs/opfs-worker-runtime.ts"; const scopeA: OpfsStorageScope = Object.freeze({ @@ -568,6 +573,130 @@ describe("OPFS dedicated worker runtime", () => { }); }); +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): 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: runtimePolicy, + 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, + async listIncomplete() { + return browserDataSuccess({ transactions: [], moreAvailable: false }); + }, + 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([]); + }); +}); + describe("OPFS worker client lifecycle", () => { it("rejects a colliding concurrent request id without replacing the first RPC", async () => { let listener: ((event: MessageEvent) => void) | undefined;