fix(storage): page orphan GC candidates by digest cursor (R-5.1)
LIST_ORPHAN_CANDIDATES returned at most 100 old chunks in directory order, committed ones included, and had no way to continue. Once more than 100 day-old committed chunks existed, every reconcile got the same referenced page, deleted nothing and reported DEADLINE_REACHED; real orphans behind it leaked quota forever. The request now takes an optional afterDigest cursor. The worker walks prefix directories and chunk names in ascending digest order and returns only digests after the cursor. The coordinator pages on with the last digest of each page until no more are available or its deadline hits. The gateway method gets the cursor as a new trailing optional parameter. Deletion safety checks (journal reference, staging receipts, grace period) are unchanged. Verified: new test "R-5.1 orphan GC pages past referenced chunks" wires the real worker runtime, client gateway and coordinator. Before the fix it failed with inspected 100, deleted 0, DEADLINE_REACHED; now both orphans (lowest and highest digest) are deleted and all 150 referenced chunks remain. The existing listOrphanCandidates call-arity assertion now expects the extra undefined cursor argument. Gates: check:architecture, check:types:app/test/web-worker, lint, test:component pass; test:unit passes except removal-fixture.test.ts, which needs gitignored release artifacts absent from a fresh worktree. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
83cf90ba27
commit
d758934e9c
@@ -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",
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -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,
|
||||
[],
|
||||
|
||||
@@ -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<BrowserDataResult<OpfsOrphanCandidateBatch>>;
|
||||
deleteOrphanChunk(
|
||||
scope: OpfsStorageScope,
|
||||
|
||||
@@ -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<OpfsOrphanCandidateBatch> {
|
||||
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<string, FileSystemDirectoryHandle>();
|
||||
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<string, FileSystemFileHandle>();
|
||||
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;
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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<void> {
|
||||
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<unknown>) => void) | undefined;
|
||||
let sequence = 0;
|
||||
return createOpfsWorkerGateway({
|
||||
worker: {
|
||||
postMessage(message) {
|
||||
void runtime.handleRequest(message).then((response) =>
|
||||
listener?.({ data: response } as MessageEvent<unknown>),
|
||||
);
|
||||
},
|
||||
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<string>): OpfsJournalPort {
|
||||
const unused = async (): Promise<never> => {
|
||||
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<unknown>) => void) | undefined;
|
||||
|
||||
Reference in New Issue
Block a user