Files
DongHyeonka 23662fb23a fix(storage): 객체를 끝까지 돈 계정 삭제 purge는 늘 partition을 지운다
문제: 승인된 LOGOUT·ACCOUNT_DELETION purge는 객체 목록을 읽고, 하나씩
지우고, 마지막에 journal 행을 한 번 센 뒤 0이면 chunk sweep으로 끝나
`chunkSweep: "COMPLETED"`를 돌려준다. 목록과 세기는 각각 한 순간만 본다.
- 다른 탭이 새 객체를 put하는 중이면 purge의 remove가 그 put이 쥔
  origin lease를 기다린다. partition에 객체가 3개 이상이면 그 put은
  목록 뒤에 commit하고 세기 전에 complete까지 끝난다. 목록에도 행 수에도
  없어 sweep이 그 chunk를 건너뛰고, 계정 삭제 뒤에도 파일이 읽힌다
  (리뷰 실험 Y1b 메모리 20/20, Chromium 6/6). 저장소 테스트는 객체
  0~1개로만 돌아서 이 틈을 놓쳤다.
- FILES_READY에서 멈춘 put의 행이 `logicalKey`를 잃으면 세지 못한다.
  staging receipt가 chunk를 sweep에서 지켜 purge마다 COMPLETED인데
  receipt·chunk·manifest가 남는다(Y2).

고른 방법: 마지막 객체까지 돈 purge는 sweep 대신 늘 partition 삭제로
끝낸다(리뷰 2.1절 (d')). exclusive partition lock이 그때 진행 중인
put·delete를 모두 기다린 뒤 디렉터리 전체(staging 포함)와 그 partition
행을 지우므로 두 경우를 함께 막는다. 객체 순회는 `removedObjects`·
`releasedBytes` 보고와 예산 단위 진행을 위해 남긴다. 예산이나 다른 탭의
변경(CONFLICT) 때문에 끝까지 돌지 못한 호출은 지금처럼
`moreObjectsAvailable: true`를 돌려주고, 그때만 journal 행을 세서 끝나지
않은 행이 있으면 바로 partition을 지운다(2026-11-03 05-01 그대로).
purge 성공 report는 이제 `partitionDeleted`와 `moreObjectsAvailable`
중 정확히 하나를 가진다(walk 뒤 abort도 more로 보고).

버린 대안:
- (a) sweep 뒤에 다시 세고 committed 객체를 한 번 더 본다: ①만 막고
  ②가 남는다. 다시 볼 때 정책상 남겨야 할 객체를 가려내려면 목록을 끝까지
  다시 읽어야 한다.
- (b)+(a): 둘 다 막지만 판단 조건이 일곱 개가 된다.
- 세기를 아예 없애기: 예산에 걸린 호출의 crash 행 처리가 다음 호출로
  밀린다. 지금 동작을 바꿀 이유가 없어 남겼다.

위험·한계:
- 모든 승인 purge가 다른 탭의 진행 중 put을 기다린다(지금까지는 끝나지
  않은 행이 있을 때만). 기다림 상한은 `mutationLockWaitTimeoutMs`
  (1103/05-02)이고 abort로 멈출 수 있다.
- 같은 partition에 LOGOUT 때 남겨야 하는 객체가 섞이면 이 방법은 맞지
  않는다. 지금 정책 검사는 OPAQUE_PARTITION이면 LOGOUT·ACCOUNT_DELETION
  모두 purge만 허용해 그런 객체가 생기지 않는다.
- port의 `chunkSweep`은 아무도 채우지 않는다. 읽는 코드가 깨지지 않게
  타입은 남기고 `@deprecated`로 적었다.
- recipe fake의 purge도 늘 `partitionDeleted`다.
- `logicalKey`를 잃은 행 자체는 여전히 남는다(05-03 설계). 그 bytes는
  이제 남지 않는다.
- Firefox·WebKit에서 Y1은 돌리지 않았다. browser spec은 객체 0·3개
  두 경우로 늘렸다.

검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/opfs-worker-runtime.test.ts
  tests/unit/opfs-byte-store.test.ts tests/unit/indexeddb-opfs-journal.test.ts
- node scripts/run-vitest.ts run tests/recipes/browser-file-storage-contracts.test.ts
- corepack pnpm test:browser-capabilities tests/browser-capabilities/opfs-runtime.spec.ts --project=chromium

Refs: 1103/05-01
2026-11-05 22:08:19 +09:00

3392 lines
110 KiB
TypeScript

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<ArrayBuffer>((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<string, OpfsPreparedObject>();
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<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,
policy = runtimePolicy,
): 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,
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,
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<OpfsPreparedObject> {
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<void>;
release: () => void;
}> {
let markStreaming!: () => void;
const streaming = new Promise<void>((resolve) => {
markStreaming = resolve;
});
let release!: () => void;
const gate = new Promise<void>((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<OpfsWorkerGateway["preparePut"]>[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<string>();
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<number[]> {
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<unknown>) => 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<unknown>);
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<unknown>) => 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<unknown>),
);
},
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<unknown>) => 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<never>(() => {});
}
held = true;
counters.acquires += 1;
let released = false;
return {
release() {
if (released) return;
released = true;
held = false;
counters.releases += 1;
},
};
},
};
}
function withTimeout<Value>(
operation: Promise<Value>,
label: string,
ms = 200,
): Promise<Value> {
return Promise.race([
operation,
new Promise<never>((_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<typeof createOpfsWorkerRuntime>,
transactionId: string,
): Promise<OpfsPreparedObject> {
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<FileSystemDirectoryHandle> {
throw new DOMException("Out of room", "QuotaExceededError");
},
async getFileHandle(): Promise<FileSystemFileHandle> {
throw new DOMException("Out of room", "QuotaExceededError");
},
async removeEntry(): Promise<void> {
throw new DOMException("Out of room", "QuotaExceededError");
},
async *entries(): AsyncIterableIterator<never> {},
} 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<unknown>) => void>();
return {
postMessage(message: unknown) {
const response = reply(message as OpfsWorkerRequest);
queueMicrotask(() => {
for (const listener of listeners) {
listener({ data: response } as MessageEvent<unknown>);
}
});
},
addEventListener(_type: "message", listener: (event: MessageEvent<unknown>) => void) {
listeners.add(listener);
},
removeEventListener(_type: "message", listener: (event: MessageEvent<unknown>) => 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<string, unknown> = {
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<unknown>) => 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<unknown>);
}
},
};
}
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<Parameters<typeof createOpfsByteStoreAdapter>[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<typeof createOpfsByteStoreAdapter>,
objectId: string,
): Promise<Readonly<{ generation: number; bytes: number[] }> | 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<MemoryNode | undefined>(
(node, segment) =>
node instanceof MemoryDirectory ? node.children.get(segment) : node,
root,
);
if (partition instanceof MemoryDirectory) walk(partition, "");
return files;
}
const putBytes = (
adapter: ReturnType<typeof createOpfsByteStoreAdapter>,
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<typeof writer.objects.put> | 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<string, unknown>;
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<typeof writer.objects.put> | 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<OpfsJournalPort[typeof parkedStep]>
) => {
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<unknown>) =>
Promise.race([
step,
new Promise((resolve) => setTimeout(resolve, 100)),
]);
const put = putBytes(writer, "object_inflight1", [8, 8]);
let purge: ReturnType<typeof purger.maintenance.enforcePolicies>;
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<unknown>,
) {
while (
!(await navigator.locks.query()).pending?.some(
(lock) => lock.name === lockName(policy) && lock.mode === "shared",
)
) {
await tick();
}
}
const settledWithin = async <Value,>(work: Promise<Value>, 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<void>;
pass: () => Promise<void>;
open: () => void;
}> {
let reach!: () => void;
const reached = new Promise<void>((resolve) => {
reach = resolve;
});
let open!: () => void;
const opened = new Promise<void>((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],
});
});
});