fix(browser-transfer): map each upload() failure recovery to one caller action (01-05)

ABORT_PENDING and a checkpoint CAS race returned the same failure, and some
recoveries (REISSUE_CAPABILITY, RESTART for a replayed create) named actions
the caller cannot take or that repeat the failure. The port now documents a
five-value recovery table and upload() returns only those values.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-25 22:22:27 +09:00
co-authored by Claude Opus 5.5
parent 5a6665a61f
commit 426b6b8eec
7 changed files with 269 additions and 25 deletions
@@ -238,7 +238,8 @@ describe("resumable upload runtime server response validation", () => {
error: {
code: "INTEGRITY_FAILED",
operation: "UPLOAD_SESSION",
recovery: "RECONCILE",
// 01-05. The create key replays the same answer.
recovery: "NONE",
},
});
});
@@ -251,7 +252,7 @@ describe("resumable upload runtime server response validation", () => {
});
});
it("restarts a session whose lifetime exceeds the policy ceiling", async () => {
it("refuses a session whose lifetime exceeds the policy ceiling", async () => {
const harness = createControlHarness();
const create = harness.control.createSession.bind(harness.control);
harness.control.createSession = async (input) => {
@@ -265,10 +266,12 @@ describe("resumable upload runtime server response validation", () => {
};
await expect(upload(dependencies(harness))).resolves.toMatchObject({
ok: false,
// 01-05. A restart gets the same session back, so there is no caller
// action; this is a server/policy mismatch.
error: {
code: "EXPIRED_RESOURCE",
code: "POLICY_REJECTED",
operation: "UPLOAD_SESSION",
recovery: "RESTART",
recovery: "NONE",
},
});
});
@@ -285,10 +288,11 @@ describe("resumable upload runtime server response validation", () => {
});
await expect(upload(dependencies(harness))).resolves.toMatchObject({
ok: false,
// 01-05. The caller's action for a capability refusal is upload().
error: {
code: "CORRUPT_DATA",
operation: "UPLOAD_PART",
recovery: "REISSUE_CAPABILITY",
recovery: "RESUME",
},
});
});
@@ -307,7 +311,7 @@ describe("resumable upload runtime server response validation", () => {
error: {
code: "POLICY_REJECTED",
operation: "UPLOAD_PART",
recovery: "REISSUE_CAPABILITY",
recovery: "RESUME",
},
});
});
@@ -326,7 +330,7 @@ describe("resumable upload runtime server response validation", () => {
error: {
code: "INTEGRITY_FAILED",
operation: "UPLOAD_RECONCILE",
recovery: "RECONCILE",
recovery: "RESTART",
},
});
});
@@ -702,3 +702,166 @@ describe("resumable upload part time limit (01-03)", () => {
}
});
});
describe("upload() failure recovery maps to one caller action (01-05)", () => {
/** The port's recovery → action table (`ResumableUploadPort.upload`). */
const UPLOAD_ACTIONS = new Set([
"RESUME",
"RECONCILE",
"RESTART",
"RESELECT",
"NONE",
]);
function runtimeFor(
harness: ReturnType<typeof createControlHarness>,
overrides: Partial<
Parameters<typeof createResumableUploadRuntime<TestCapability>>[0]
> = {},
) {
return createResumableUploadRuntime({
controlPlane: harness.control,
partExecutor: executorFor(harness),
checkpoints: new MemoryCheckpointStore(),
mutationLock: noContentionLock,
crypto,
policy: runtimePolicy({ maxRetries: 0 }),
now: () => 1_000,
sleep: async () => {},
...overrides,
});
}
const scenarios = {
"an abort is still pending": async () => {
const harness = createControlHarness();
harness.control.complete = async () =>
browserDataFailure("UNAVAILABLE", "UPLOAD_COMPLETE", {
retryable: true,
recovery: "RESUME",
});
harness.control.abort = async () =>
browserDataFailure("UNAVAILABLE", "UPLOAD_ABORT", {
retryable: true,
recovery: "RESUME",
});
const runtime = runtimeFor(harness);
const key = "upload_key_abort_pending";
await runtime.upload(request(key));
await runtime.abort({ uploadKey: key, signal: activeSignal });
return await runtime.upload(request(key));
},
"another context wrote the checkpoint first": async () => {
const checkpoints = new MemoryCheckpointStore();
checkpoints.compareAndSwap = async () =>
browserDataFailure("CONFLICT", "UPLOAD_RECONCILE", {
recovery: "RECONCILE",
});
return await runtimeFor(createControlHarness(), { checkpoints }).upload(
request("upload_key_cas_conflict"),
);
},
"the server status disagrees with the file": async () =>
await runtimeFor(
createControlHarness({
statusParts: (_session, accepted) =>
[...accepted.values()].map((part) => ({
...part,
checksumSha256: "e".repeat(64),
})),
}),
).upload(request("upload_key_status_mismatch")),
"the checkpoint row is unreadable": async () => {
const checkpoints = new MemoryCheckpointStore();
checkpoints.read = async () =>
browserDataFailure("CORRUPT_DATA", "UPLOAD_RECONCILE", {
recovery: "RECONCILE",
});
return await runtimeFor(createControlHarness(), { checkpoints }).upload(
request("upload_key_unreadable"),
);
},
"the server session outlives the policy": async () => {
const harness = createControlHarness();
const create = harness.control.createSession.bind(harness.control);
harness.control.createSession = async (input) => {
const created = await create(input);
return created.ok
? browserDataSuccess({
...created.value,
expiresAtEpochMs: 1_000 + 20_000,
})
: created;
};
return await runtimeFor(harness).upload(request("upload_key_long_session"));
},
"every PUT refuses the capability": async () =>
await runtimeFor(createControlHarness(), {
partExecutor: { uploadPart: async () => putForbidden() },
}).upload(request("upload_key_refused_put")),
"the key belongs to another file": async () => {
const checkpoints = new MemoryCheckpointStore();
const harness = createControlHarness();
harness.control.complete = async () =>
browserDataFailure("UNAVAILABLE", "UPLOAD_COMPLETE", {
retryable: true,
recovery: "RESUME",
});
const runtime = runtimeFor(harness, { checkpoints });
const key = "upload_key_other_file";
await runtime.upload(request(key));
return await runtime.upload({
...request(key),
source: rangeSource(new Uint8Array([9, 9, 9, 9])),
});
},
} as const;
it.each([
["an abort is still pending", "CONFLICT", "UPLOAD_ABORT", "RESTART"],
[
"another context wrote the checkpoint first",
"CONFLICT",
"UPLOAD_RECONCILE",
"RECONCILE",
],
[
"the server status disagrees with the file",
"INTEGRITY_FAILED",
"UPLOAD_RECONCILE",
"RESTART",
],
[
"the checkpoint row is unreadable",
"CORRUPT_DATA",
"UPLOAD_RECONCILE",
"RESTART",
],
[
"the server session outlives the policy",
"POLICY_REJECTED",
"UPLOAD_SESSION",
"NONE",
],
[
"every PUT refuses the capability",
"PERMISSION_DENIED",
"UPLOAD_PART",
"RESUME",
],
[
"the key belongs to another file",
"STALE_RESULT",
"UPLOAD_RECONCILE",
"RESELECT",
],
] as const)("%s → %s/%s/%s", async (scenario, code, operation, recovery) => {
const result = await scenarios[scenario]();
expect(result).toMatchObject({
ok: false,
error: { code, operation, recovery },
});
if (!result.ok) expect(UPLOAD_ACTIONS.has(result.error.recovery)).toBe(true);
});
});
+3 -1
View File
@@ -371,12 +371,14 @@ describe("production resumable upload runtime", () => {
source: rangeSource(new Uint8Array([1, 2, 3, 4])),
signal: activeSignal,
});
// 01-05. Calling upload() again reads the same server parts, so the way
// out is abort() and a fresh session.
expect(result).toMatchObject({
ok: false,
error: {
code: "INTEGRITY_FAILED",
operation: "UPLOAD_RECONCILE",
recovery: "RECONCILE",
recovery: "RESTART",
},
});
expect(partExecutor.uploadPart).not.toHaveBeenCalled();