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:
DongHyeonka
2026-09-24 12:27:48 +09:00
co-authored by Claude Opus 5.5
parent 83cf90ba27
commit d758934e9c
6 changed files with 222 additions and 58 deletions
@@ -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;
+2
View File
@@ -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,
+129
View File
@@ -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;