fix(browser-transfer): let abort drop an unreadable checkpoint row (Q-6.1-6)

A corrupt row, or one a newer build wrote with an unknown schemaVersion,
failed both upload and abort with CORRUPT_DATA until the whole partition
was deleted. The checkpoint store port gains an optional
removeUnreadable(): in one transaction it deletes the row only if it does
not parse as a checkpoint (a readable row is CONFLICT, an absent row is a
success). Explicit abort calls it on a CORRUPT_DATA read and reports
ORPHANED; the server session is left to expire because the row names no
session. upload() still fails closed on such a row. The port change is
additive (optional method); the architecture doc notes the exception.

Verified: RED tests "removes an unreadable checkpoint row on abort and
reports ORPHANED" (was CORRUPT_DATA) and "removes only an unreadable row
without a revision" (method missing) + all gates.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-24 13:32:37 +09:00
co-authored by Claude Opus 5.5
parent e83cda6f7f
commit 879ceda3bb
6 changed files with 171 additions and 1 deletions
@@ -360,7 +360,10 @@ resume through upload()
정한 `schemaVersion: 2`가 필요하다. 기존 schema에 필드를 몰래 추가하지 않는다.
현재 checkpoint store도 single-key `read/CAS/remove`와 account partition 전체
삭제만 제공한다. abandoned upload가 같은 `uploadKey`로 다시 열리지 않으면 local
삭제만 제공한다. 예외로 읽을 수 없는 행(손상, 또는 이 빌드가 모르는
`schemaVersion`)은 명시적 `abort()`가 `removeUnreadable`로 지우고 `ORPHANED`로
보고한다. 그 행에서는 session을 알 수 없으므로 server session은 만료에 맡긴다.
`upload()`는 같은 행에서 계속 `CORRUPT_DATA`로 fail-closed한다. abandoned upload가 같은 `uploadKey`로 다시 열리지 않으면 local
checkpoint를 retention 기준으로 자동 발견·정리하지 못한다. 향후 admin lifecycle은
다음을 제공한다.
@@ -415,6 +415,45 @@ export function createIndexedDbResumableUploadCheckpointRuntime(
);
},
async removeUnreadable(
inputValue: Parameters<
NonNullable<ResumableUploadCheckpointStore["removeUnreadable"]>
>[0],
): Promise<BrowserDataResult<void>> {
if (!SAFE_UPLOAD_KEY.test(inputValue.uploadKey)) {
return browserDataFailure("INVALID_INPUT", OPERATION);
}
const opened = await connection.acquire(inputValue.signal);
if (!opened.ok) return opened;
return await runCheckpointTransaction<void>(
opened.value,
"readwrite",
inputValue.signal,
(nativeStore, context) => {
const request = nativeStore.get(inputValue.uploadKey);
request.onerror = () => context.fail(mappedFailure(request.error));
request.onsuccess = () => {
// Checked in the same transaction as the delete, so a row another
// context rewrote as a valid checkpoint is never dropped.
if (request.result === undefined) {
context.succeed(undefined);
return;
}
if (isResumableUploadCheckpoint(request.result)) {
context.fail(
checkpointFailure("CONFLICT", { recovery: "RECONCILE" }),
);
return;
}
const deletion = nativeStore.delete(inputValue.uploadKey);
deletion.onerror = () =>
context.fail(mappedFailure(deletion.error));
deletion.onsuccess = () => context.succeed(undefined);
};
},
);
},
close() {
connection.close();
},
@@ -1168,6 +1168,21 @@ async function executeAbort<Capability>(
signal: AbortSignal,
): Promise<BrowserDataResult<UploadAbortOutcome>> {
const found = await dependencies.checkpoints.read(uploadKey, signal);
if (
!found.ok &&
found.error.code === "CORRUPT_DATA" &&
dependencies.checkpoints.removeUnreadable
) {
// Q-6.1-6. A row this build cannot read names no session to abort, so
// explicit abort drops it and leaves the server session to expire.
const removed = await dependencies.checkpoints.removeUnreadable({
uploadKey,
signal,
});
return removed.ok
? browserDataSuccess(Object.freeze({ state: "ORPHANED" as const }))
: remapResult(removed, "UPLOAD_ABORT");
}
if (!found.ok) return remapResult(found, "UPLOAD_ABORT");
if (!found.value) {
return browserDataSuccess(Object.freeze({ state: "NOT_FOUND" }));
@@ -1977,11 +1992,14 @@ function snapshotCheckpointStore(
const read = value?.read;
const compareAndSwap = value?.compareAndSwap;
const remove = value?.remove;
const removeUnreadable = value?.removeUnreadable;
const close = value?.close;
if (
typeof read !== "function" ||
typeof compareAndSwap !== "function" ||
typeof remove !== "function" ||
(removeUnreadable !== undefined &&
typeof removeUnreadable !== "function") ||
typeof close !== "function"
) {
throw new TypeError("Upload checkpoint store is invalid.");
@@ -2005,6 +2023,15 @@ function snapshotCheckpointStore(
) {
return await remove.call(value, input);
},
...(removeUnreadable
? {
async removeUnreadable(
input: Parameters<typeof removeUnreadable>[0],
) {
return await removeUnreadable.call(value, input);
},
}
: {}),
close() {
close.call(value);
},
@@ -273,6 +273,18 @@ export interface ResumableUploadCheckpointStore {
expectedRevision: number;
signal?: AbortSignal;
}>): Promise<BrowserDataResult<void>>;
/**
* Q-6.1-6. Deletes the row only when it cannot be read as a checkpoint
* (corrupt, or written by a schema this build does not know); a readable row
* is left alone and reported as `CONFLICT`. An absent row is a success.
* Explicit abort uses it so such a row does not block the upload key until
* the whole partition is deleted. Optional: a store without it keeps the
* old behavior.
*/
removeUnreadable?(input: Readonly<{
uploadKey: string;
signal?: AbortSignal;
}>): Promise<BrowserDataResult<void>>;
close(): void;
}
@@ -317,6 +317,43 @@ describe("IndexedDB resumable upload checkpoint", () => {
});
});
// Q-6.1-6. The revision-free delete exists only for rows this build cannot
// read; a readable checkpoint still needs the exact-revision remove.
it("removes only an unreadable row without a revision", async () => {
const memory = new MemoryIndexedDbFactory();
const store = createIndexedDbResumableUploadCheckpointStore({
scope,
factory: memory.factory,
});
const readable = checkpoint(1);
expect(
await store.compareAndSwap({ expectedRevision: null, checkpoint: readable }),
).toMatchObject({ ok: true });
expect(
await store.removeUnreadable?.({ uploadKey: readable.uploadKey }),
).toMatchObject({
ok: false,
error: { code: "CONFLICT", recovery: "RECONCILE" },
});
expect(await store.read(readable.uploadKey)).toEqual({
ok: true,
value: readable,
});
memory.seed("checkpoints", { ...readable, schemaVersion: 2 });
expect(await store.read(readable.uploadKey)).toMatchObject({
ok: false,
error: { code: "CORRUPT_DATA" },
});
expect(
await store.removeUnreadable?.({ uploadKey: readable.uploadKey }),
).toEqual({ ok: true, value: undefined });
expect(await store.read(readable.uploadKey)).toEqual({
ok: true,
value: null,
});
});
it("closes the bound partition before successful lifecycle deletion", async () => {
const memory = new MemoryIndexedDbFactory();
const runtime = createIndexedDbResumableUploadCheckpointRuntime({
@@ -23,6 +23,7 @@ import {
browserDataFailure,
browserDataSuccess,
} from "../../src/adapters/browser-file-storage/result.ts";
import { createIndexedDbResumableUploadCheckpointStore } from "../../src/adapters/browser-transfer/resumable-upload/indexeddb-checkpoint-store.ts";
import { createPresignedUploadPartExecutor } from "../../src/adapters/browser-transfer/resumable-upload/presigned-upload-part-executor.ts";
import { createResumableUploadRuntime } from "../../src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts";
import { resolveResumableUploadRuntimePolicy } from "../../src/adapters/browser-transfer/resumable-upload/runtime-policy.ts";
@@ -31,6 +32,7 @@ import type {
UploadCancellationListener,
} from "../../src/adapters/browser-transfer/resumable-upload/upload-cancellation-channel.ts";
import type { UploadMutationLock } from "../../src/adapters/browser-transfer/resumable-upload/upload-mutation-lock.ts";
import { MemoryIndexedDbFactory } from "../helpers/memory-indexeddb.ts";
import {
activeSignal,
@@ -810,6 +812,56 @@ describe("production resumable upload runtime", () => {
);
});
// Q-6.1-6. A row this build cannot read (here a newer schemaVersion left by
// a rolled-back release) used to fail both upload and abort with
// CORRUPT_DATA until the whole partition was deleted.
it("removes an unreadable checkpoint row on abort and reports ORPHANED", async () => {
const memory = new MemoryIndexedDbFactory();
const checkpoints = createIndexedDbResumableUploadCheckpointStore({
scope: {
authorityToken: "authority_token_01",
namespaceToken: "namespace_token_01",
partitionToken: "partition_token_01",
},
factory: memory.factory,
});
// Opens the database so the object stores exist before seeding.
expect(await checkpoints.read("upload_key_unreadable")).toEqual({
ok: true,
value: null,
});
memory.seed("checkpoints", {
schemaVersion: 2,
uploadKey: "upload_key_unreadable",
revision: 7,
state: "PAUSED",
});
const harness = createControlHarness();
const serverAbort = vi.spyOn(harness.control, "abort");
const runtime = createResumableUploadRuntime({
controlPlane: harness.control,
partExecutor: executorFor(harness),
checkpoints,
mutationLock: noContentionLock,
crypto,
policy: runtimePolicy(),
now: () => 1_000,
sleep: async () => {},
});
expect(
await runtime.abort({
uploadKey: "upload_key_unreadable",
signal: activeSignal,
}),
).toEqual({ ok: true, value: { state: "ORPHANED" } });
// No session id can be read from the row, so the server is not called.
expect(serverAbort).not.toHaveBeenCalled();
expect(memory.readRaw("checkpoints", "upload_key_unreadable")).toBe(
undefined,
);
});
it("interrupts a same-runtime active upload before explicit abort waits for the key lock", async () => {
const checkpoints = new MemoryCheckpointStore();
const harness = createControlHarness();